Anthropic
POST /v1/messages recibe unha solicitude no formato Anthropic Messages e responde no mesmo formato, con streaming ou sen el. Úsao co SDK de Anthropic e con ferramentas baseadas nel, como Claude Code: define a URL base, usa a túa clave API de Shannon e indica un id de modelo de Shannon.
POST https://api.shannon-ai.com/v1/messages
Apunta o SDK de Anthropic á URL base de Shannon. O SDK engade /v1/messages e envía a túa clave na cabeceira x-api-key.
import anthropic
client = anthropic.Anthropic(
api_key="YOUR_API_KEY",
base_url="https://api.shannon-ai.com",
)
message = client.messages.create(
model="shannon-3",
max_tokens=1024,
messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
for block in message.content:
if block.type == "text":
print(block.text) import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com",
});
const message = await client.messages.create({
model: "shannon-3",
max_tokens: 1024,
messages: [{ role: "user", content: "Say hello in one sentence." }],
});
for (const block of message.content) {
if (block.type === "text") console.log(block.text);
} curl https://api.shannon-ai.com/v1/messages \
-H "x-api-key: YOUR_API_KEY" \
-H "content-type: application/json" \
-d '{
"model": "shannon-3",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Say hello in one sentence."}]
}' A resposta é unha mensaxe cuxo content é unha lista de bloques. Atopa os bloques polo seu type: cando o modelo razoou, o primeiro bloque é thinking e o texto vén despois.
{
"id": "msg_5f0c1e7a9b3d4c62a8e1f07d2b46c9a3",
"type": "message",
"role": "assistant",
"model": "shannon-3",
"content": [
{
"type": "thinking",
"thinking": "The user wants a greeting in one sentence. Keep it short and friendly."
},
{
"type": "text",
"text": "Hello, it is good to meet you."
}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 1184,
"output_tokens": 46
}
} Cabeceiras
| Cabeceira | Valor | Descrición |
|---|---|---|
x-api-key | YOUR_API_KEY | A túa clave API. No seu lugar acéptase Authorization: Bearer YOUR_API_KEY. |
content-type | application/json | Obrigatoria. |
anthropic-version | 2023-06-01 | Aceptada, non obrigatoria. O SDK de Anthropic envía 2023-06-01; a resposta ten o mesmo formato sexa cal sexa o valor. |
anthropic-beta | Aceptada, non obrigatoria. | |
x-request-id | Opcional. O teu propio id para a solicitude. Volve sen cambios na resposta; sen el, a resposta leva un id de 12 caracteres hexadecimais. |
Campos da solicitude
Só messages é obrigatorio. A columna Aplicado por indica os modelos nos que un campo cambia a resposta. Os modelos open-weight alojados son os doce ids da lista de modelos; a familia Shannon 3 é shannon-3, shannon-3-pro, shannon-3.1 e shannon-3.1-pro. Modelos e prezos
| Campo | Tipo | Valor predeterminado | Descrición | Aplicado por |
|---|---|---|---|---|
model | string | shannon-1.6-lite | Un id de modelo de Shannon da lista de modelos. Envíao en cada solicitude. A coincidencia non distingue maiúsculas de minúsculas. Calquera outro nome devolve 400 unknown model, así que unha ferramenta que envía os seus propios nomes de modelo debe configurarse cun id de Shannon. | Todos os modelos |
messages | array | Obrigatorio. A conversa, coa mensaxe máis antiga primeiro, cos roles user e assistant. Consulta Mensaxes e bloques de contido máis abaixo. | Todos os modelos | |
system | string | array | Instrucións para o modelo: unha cadea ou unha matriz de bloques de texto. Consulta System prompt máis abaixo. | Modelos open-weight alojados, shannon-1.6-*, shannon-2-*, shannon-coder-1 | |
max_tokens | integer | 4096 | Límite superior da resposta, en tokens. Opcional neste endpoint; o SDK de Anthropic sempre o envía. Un valor fóra do intervalo de 1 a 65,536 axústase a ese intervalo. É tamén a cantidade que se reserva do teu saldo mentres a solicitude está en curso. | Modelos open-weight alojados, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 |
stream | boolean | false | true envía a resposta como server-sent events. Consulta Streaming máis abaixo. | Todos os modelos |
temperature | number | Temperatura de mostraxe. Nos modelos open-weight alojados os valores mantéñense entre 0 e 2. | Modelos open-weight alojados, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 | |
top_p | number | Mostraxe por núcleo (nucleus sampling). | Modelos open-weight alojados | |
stop_sequences | array | Ata 4 cadeas. A resposta remata antes da primeira que apareza. stop_reason segue sendo end_turn. | Modelos open-weight alojados | |
tools | array | As ferramentas ás que pode chamar o modelo, cada unha como {"name", "description", "input_schema"}. Consulta Tools máis abaixo. | Todos os modelos | |
tool_choice | object | {"type": "auto"} deixa que decida o modelo, {"type": "any"} obrígao a chamar a unha ferramenta, {"type": "tool", "name": "…"} obrígao a chamar a esa ferramenta. | Modelos open-weight alojados | |
thinking | object | Canto razoa o modelo antes de responder. Consulta Thinking máis abaixo. | Modelos open-weight alojados | |
web_search | boolean | false | Unha adición de Shannon ao formato: true permite que o modelo busque na web antes de responder. | shannon-1.6-*, shannon-2-*, familia Shannon 3 |
Sen max_tokens o valor é 4,096, e 65,536 en shannon-coder-1.
Acéptanse metadata, top_k, service_tier e os marcadores cache_control nos bloques para que o código de cliente existente funcione sen cambios. Non alteran a resposta; a caché de prompts nos modelos open-weight alojados é automática.
Unha resposta JSON segundo un esquema pídese con response_format en Chat Completions e con text.format en Responses. Saídas estruturadas
Unha solicitude cun system prompt e thinking
Esta solicitude envía un system prompt, un orzamento de thinking, unha temperatura e unha secuencia de parada. Usa un modelo open-weight alojado, que aplica todos eles.
import anthropic
client = anthropic.Anthropic(
api_key="YOUR_API_KEY",
base_url="https://api.shannon-ai.com",
)
message = client.messages.create(
model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
max_tokens=4096,
system="You are a physics teacher. Answer in two sentences.",
thinking={"type": "enabled", "budget_tokens": 2048},
temperature=0.3,
stop_sequences=["\n\n"],
messages=[{"role": "user", "content": "Why is the sky blue?"}],
)
for block in message.content:
if block.type == "thinking":
print("reasoning:", block.thinking)
elif block.type == "text":
print("answer:", block.text)
print(message.usage) import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com",
});
const message = await client.messages.create({
model: "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
max_tokens: 4096,
system: "You are a physics teacher. Answer in two sentences.",
thinking: { type: "enabled", budget_tokens: 2048 },
temperature: 0.3,
stop_sequences: ["\n\n"],
messages: [{ role: "user", content: "Why is the sky blue?" }],
});
for (const block of message.content) {
if (block.type === "thinking") console.log("reasoning:", block.thinking);
if (block.type === "text") console.log("answer:", block.text);
}
console.log(message.usage); curl https://api.shannon-ai.com/v1/messages \
-H "x-api-key: YOUR_API_KEY" \
-H "content-type: application/json" \
-d '{
"model": "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
"max_tokens": 4096,
"system": "You are a physics teacher. Answer in two sentences.",
"thinking": {"type": "enabled", "budget_tokens": 2048},
"temperature": 0.3,
"stop_sequences": ["\n\n"],
"messages": [{"role": "user", "content": "Why is the sky blue?"}]
}' Nos modelos open-weight alojados, usage informa dos tokens lidos da caché de prompts por separado do resto de tokens de entrada.
{
"usage": {
"input_tokens": 31,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 62
}
} System prompt
system é unha cadea ou unha matriz de bloques de texto coa forma [{"type": "text", "text": "…"}]. Os textos dos bloques únense cun salto de liña.
Aplícano os modelos open-weight alojados, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro e shannon-coder-1. Cun id da familia Shannon 3, pon na mensaxe do usuario as instrucións que deban cumprirse.
Mensaxes e bloques de contido
Unha mensaxe ten un role, user ou assistant, e un content. content é unha cadea ou unha matriz de bloques.
| Bloque | Descrición | Dispoñible en |
|---|---|---|
{"type": "text", "text": "…"} | Texto. | Todos os modelos |
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "…"}}{"type": "image", "source": {"type": "url", "url": "…"}} | Unha imaxe nunha mensaxe user, en base64 ou por URL. | Familia Shannon 3, shannon-1.6-lite, shannon-1.6-pro e os modelos open-weight alojados que admiten imaxes como entrada |
{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} | Un documento (PDF, Word, PowerPoint ou Excel) nunha mensaxe user, en base64 ou por URL. | Familia Shannon 3 |
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} | Nunha mensaxe assistant: unha chamada a unha ferramenta que fixo o modelo nunha resposta anterior. | Todos os modelos |
{"type": "tool_result", "tool_use_id": "toolu_…", "content": "…"} | Nunha mensaxe user: o resultado desa chamada. content é unha cadea ou unha lista de bloques de texto. | Todos os modelos |
Podes devolver tal cal o content dunha resposta anterior: os bloques text e tool_use lense e os bloques thinking omítense.
Nos niveis Shannon, as imaxes e os documentos lense da última mensaxe user. Os tamaños e os límites teñen a súa propia páxina. Imaxes e ficheiros
Thinking
Os modelos open-weight alojados asignan thinking a un esforzo de razoamento. Sen o campo, o esforzo é alto.
| Forma | budget_tokens | Efecto |
|---|---|---|
{"type": "disabled"} | Sen razoamento. A resposta non ten bloque thinking. | |
{"type": "enabled", "budget_tokens": 2048} | ≤ 2,048 | Esforzo baixo. |
{"type": "enabled", "budget_tokens": 8192} | ≤ 8,192 | Esforzo medio. |
{"type": "enabled", "budget_tokens": 16000} | > 8,192 | Esforzo alto. |
Un modelo que razoa devolve o seu razoamento como un bloque {"type": "thinking", "thinking": "…"} diante do texto. Os niveis Shannon que razoan tamén o envían.
Os esforzos descríbense na súa propia páxina. Esforzo de razoamento
Ferramentas
Unha ferramenta é unha función que executa o teu código. Descríbea con name, description e input_schema. Cando o modelo quere unha ferramenta, a resposta contén un bloque tool_use e stop_reason é tool_use.
Unha definición de ferramenta en tools:
[
{
"name": "get_weather",
"description": "Current weather for a city.",
"input_schema": {
"type": "object",
"properties": {
"city": {
"type": "string"
}
},
"required": [
"city"
]
}
}
] O content dunha resposta que a chama:
[
{
"type": "text",
"text": ""
},
{
"type": "tool_use",
"id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
"name": "get_weather",
"input": {
"city": "Paris"
}
}
] Executa a ferramenta e envía a solicitude de novo coa chamada e un bloque tool_result engadidos a messages:
[
{
"role": "user",
"content": "What is the weather in Paris?"
},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
"name": "get_weather",
"input": {
"city": "Paris"
}
}
]
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
"content": "{\"temperature_c\": 18, \"sky\": \"cloudy\"}"
}
]
}
] tool_choice
| Forma | Efecto | Aplicado por |
|---|---|---|
{"type": "auto"} | O modelo decide se chama a unha ferramenta. Este é o valor predeterminado. | Todos os modelos |
{"type": "any"} | O modelo debe chamar a unha das ferramentas. | Modelos open-weight alojados |
{"type": "tool", "name": "…"} | O modelo debe chamar á ferramenta indicada. | Modelos open-weight alojados |
Só se len as ferramentas con input_schema. A busca web non é unha ferramenta neste endpoint: define o campo web_search.
O bucle de ferramentas descríbese por completo na súa propia páxina. Chamadas a funcións
A resposta
| Campo | Tipo | Descrición | Enviado por |
|---|---|---|---|
id | string | msg_ seguido de 32 caracteres hexadecimais. | Todos os modelos |
type | string | Sempre message. | Todos os modelos |
role | string | Sempre assistant. | Todos os modelos |
model | string | O id canónico do modelo que respondeu. | Todos os modelos |
content | array | Os bloques da resposta, nesta orde: thinking cando o modelo razoou, text e despois un tool_use por cada chamada a unha ferramenta. | Todos os modelos |
stop_reason | string | Por que rematou a resposta. Consulta os valores a continuación. | Todos os modelos |
usage | object | input_tokens e output_tokens. | Todos os modelos |
sources | array | Só nunha solicitude con web_search: true cuxa busca atopou algo: os resultados que recibiu o modelo, cada un con index, title e url. [1] na resposta é a entrada con index 1. Nun stream chega co evento message_delta. | shannon-1.6-*, shannon-2-*, familia Shannon 3 |
usage.cache_read_input_tokens | integer | cache_read_input_tokens é a parte do prompt lida da caché; input_tokens é o resto. cache_creation_input_tokens é sempre 0. | Modelos open-weight alojados |
Bloques da resposta
| Bloque | Descrición |
|---|---|
{"type": "thinking", "thinking": "…"} | O razoamento do modelo. Non hai membro signature. |
{"type": "text", "text": "…"} | O texto da resposta. Pode estar baleiro cando a resposta é unha chamada a unha ferramenta. |
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} | Unha chamada a unha ferramenta. input é un obxecto JSON. Devolve o resultado co mesmo id. |
stop_reason
| stop_reason | Descrición | Enviado por |
|---|---|---|
end_turn | O modelo rematou a súa resposta, ou apareceu unha das túas stop_sequences. | Todos os modelos |
tool_use | A resposta contén unha ou varias chamadas a ferramentas. | Todos os modelos |
max_tokens | A resposta cortouse no límite de saída. | Familia Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1, en streams |
Streaming
Define stream como true para obter server-sent events. Cada frame ten unha liña event: co nome do evento e unha liña data: cun obxecto JSON que repite o nome en type. Os axudantes de stream do SDK de Anthropic len estes eventos por ti:
import anthropic
client = anthropic.Anthropic(
api_key="YOUR_API_KEY",
base_url="https://api.shannon-ai.com",
)
with client.messages.stream(
model="shannon-3",
max_tokens=1024,
messages=[{"role": "user", "content": "Explain server-sent events in three sentences."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
message = stream.get_final_message()
print()
print(message.stop_reason, message.usage) import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com",
});
const stream = client.messages.stream({
model: "shannon-3",
max_tokens: 1024,
messages: [{ role: "user", content: "Explain server-sent events in three sentences." }],
});
stream.on("text", (text) => process.stdout.write(text));
const message = await stream.finalMessage();
console.log("\n", message.stop_reason, message.usage); curl -N https://api.shannon-ai.com/v1/messages \
-H "x-api-key: YOUR_API_KEY" \
-H "content-type: application/json" \
-d '{
"model": "shannon-3",
"max_tokens": 1024,
"stream": true,
"messages": [{"role": "user", "content": "Explain server-sent events in three sentences."}]
}' Os eventos, na orde na que chegan:
| Evento | Datos | Cando |
|---|---|---|
message_start | message | Sempre o primeiro. message contén o id, o rol, o modelo, un content baleiro e un usage que comeza en cero. |
content_block_start | index, content_block | Ábrese un bloque. content_block é un bloque text ou thinking baleiro, ou un bloque tool_use co seu id e name. |
content_block_delta | index, delta {"type": "thinking_delta", "thinking"} | Un anaco do razoamento, para un bloque thinking. |
content_block_delta | index, delta {"type": "text_delta", "text"} | Un anaco da resposta, para un bloque text. |
content_block_delta | index, delta {"type": "input_json_delta", "partial_json"} | Os argumentos dunha chamada a unha ferramenta, completos nun só delta, para un bloque tool_use. |
content_block_stop | index | O bloque con este index está completo. |
message_delta | delta {stop_reason, stop_sequence}, usage | O final da resposta: delta.stop_reason e o usage da solicitude. |
message_stop | Sempre o último. |
Os bloques numéranse por index na orde na que se abren, e un bloque remata antes de que se abra o seguinte. Le cada bloque polo seu tipo, non polo seu número: un stream pode abrir primeiro un bloque text baleiro, despois o bloque thinking, e entregar a resposta nun bloque text posterior.
event: message_start
data: {"type":"message_start","message":{"id":"msg_5f0c…","type":"message","role":"assistant","model":"shannon-3","content":[],"usage":{"input_tokens":0,"output_tokens":0}}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"thinking","thinking":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"thinking_delta","thinking":"Three sentences: what it is, how it is framed, why it is used."}}
event: ping
data: {"type": "ping"}
event: content_block_stop
data: {"type":"content_block_stop","index":1}
event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"text","text":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":2,"delta":{"type":"text_delta","text":"Server-sent events let a server push text over one HTTP reply."}}
event: content_block_stop
data: {"type":"content_block_stop","index":2}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":1190,"output_tokens":84}}
event: message_stop
data: {"type":"message_stop"} Keep-alive
| Enviado por | Descrición |
|---|---|
Familia Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 | Un evento ping co dato {"type": "ping"}, cada 15 segundos. |
| Modelos open-weight alojados | Unha liña de comentario : keepalive, cada 15 segundos mentres o modelo traballa. |
Un stream que falla
Un fallo despois de iniciarse o stream é un evento error co mesmo corpo que unha resposta de erro: {"type": "error", "error": {"type", "message"}}. Os eventos de peche, message_delta e message_stop, seguen chegando. Considera a resposta como fallida e envía a solicitude de novo.
Erros
Os erros usan o corpo de erro de Anthropic: type é error e o obxecto error contén un type e un message. A táboa mostra o que este endpoint devolve con máis frecuencia. A lista completa, con indicacións sobre que reintentar, ten a súa propia páxina. Xestión de erros
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} | Estado | Tipo | Mensaxe | Cando |
|---|---|---|---|
401 | authentication_error | Missing authenticationInvalid API key | Non se enviou ningunha clave API, ou a clave é descoñecida ou está revogada. |
400 | invalid_request_error | unknown model: <id> | model non é un id de modelo de Shannon. |
400 | invalid_request_error | No user message provided | Niveis Shannon: a solicitude non ten texto de usuario nin tools. |
400 | invalid_request_error | <id> does not accept image input | Enviouse unha imaxe a un modelo open-weight alojado sen entrada de imaxe. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | Falta messages, ou un campo ten o tipo JSON incorrecto. |
429 | rate_limit_error | Quota exceeded. Upgrade your plan at shannon-ai.com/plan | max_tokens é maior que o que queda do teu saldo. |
429 | rate_limit_error | Too many requests. Retry in <n>s. | Protección contra inundación: máis de 120 solicitudes nun minuto na túa conta. |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | shannon-coder-1: usaches as chamadas de Shannon Coder do teu plan para a xanela actual de 4 horas. |
500 | server_error | The model backend failed to answer. Please retry. | O modelo non produciu unha resposta. Envía a solicitude de novo. |
502 | api_error | The model backend failed to answer. Please retry. | O modelo non produciu unha resposta. Envía a solicitude de novo. |
Contar tokens
POST /v1/messages/count_tokens recibe o mesmo corpo que unha solicitude de mensaxe (model, system, messages, tools) e devolve {"input_tokens": n}: o número de tokens de entrada que se cobrarían pola solicitude. Conta para os modelos open-weight alojados, é gratuíto e a protección contra inundación non o contabiliza.
import anthropic
client = anthropic.Anthropic(
api_key="YOUR_API_KEY",
base_url="https://api.shannon-ai.com",
)
count = client.messages.count_tokens(
model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
system="You are a physics teacher. Answer in two sentences.",
messages=[{"role": "user", "content": "Why is the sky blue?"}],
)
print(count.input_tokens) import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com",
});
const count = await client.messages.countTokens({
model: "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
system: "You are a physics teacher. Answer in two sentences.",
messages: [{ role: "user", content: "Why is the sky blue?" }],
});
console.log(count.input_tokens); curl https://api.shannon-ai.com/v1/messages/count_tokens \
-H "x-api-key: YOUR_API_KEY" \
-H "content-type: application/json" \
-d '{
"model": "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
"system": "You are a physics teacher. Answer in two sentences.",
"messages": [{"role": "user", "content": "Why is the sky blue?"}]
}'
# {"input_tokens": 31} A contaxe ten a súa propia páxina, co endpoint de texto simple e os límites. Reconto de tokens