Formato Anthropic
POST /v1/messages recebe uma requisição no formato Anthropic Messages e responde no mesmo formato, com ou sem streaming. Use-o com o SDK da Anthropic e com ferramentas construídas sobre ele, como o Claude Code: defina a base URL, use sua chave de API da Shannon e informe um id de modelo Shannon.
POST https://api.shannon-ai.com/v1/messages
Aponte o SDK da Anthropic para a base URL da Shannon. O SDK acrescenta /v1/messages e envia sua chave no header 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 é uma mensagem cujo content é uma lista de blocos. Encontre os blocos pelo type: quando o modelo raciocinou, o primeiro bloco é thinking e o texto vem depois dele.
{
"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
}
} Headers
| Header | Valor | Descrição |
|---|---|---|
x-api-key | YOUR_API_KEY | Sua chave de API. Authorization: Bearer YOUR_API_KEY é aceito no lugar dela. |
content-type | application/json | Obrigatório. |
anthropic-version | 2023-06-01 | Aceito, não obrigatório. O SDK da Anthropic envia 2023-06-01; a resposta tem o mesmo formato, seja qual for o valor. |
anthropic-beta | Aceito, não obrigatório. | |
x-request-id | Opcional. Seu próprio id para a requisição. Ele volta inalterado na resposta; sem ele, a resposta traz um id de 12 caracteres hexadecimais. |
Campos da requisição
Apenas messages é obrigatório. A coluna Aplicado por indica os modelos nos quais um campo muda a resposta. Os modelos open-weight hospedados são os doze ids da lista de modelos; a família Shannon 3 é shannon-3, shannon-3-pro, shannon-3.1 e shannon-3.1-pro. Modelos e preços
| Campo | Tipo | Padrão | Descrição | Aplicado por |
|---|---|---|---|---|
model | string | shannon-1.6-lite | Um id de modelo Shannon da lista de modelos. Envie-o em toda requisição. A correspondência não diferencia maiúsculas de minúsculas. Qualquer outro nome retorna 400 unknown model, então uma ferramenta que envia seus próprios nomes de modelo precisa ser configurada com um id Shannon. | Todos os modelos |
messages | array | Obrigatório. A conversa, da mensagem mais antiga para a mais recente, com os papéis user e assistant. Veja Mensagens e blocos de conteúdo abaixo. | Todos os modelos | |
system | string | array | Instruções para o modelo: uma string ou um array de blocos de texto. Veja Prompt de sistema abaixo. | Modelos open-weight hospedados, shannon-1.6-*, shannon-2-*, shannon-coder-1 | |
max_tokens | integer | 4096 | Limite máximo da resposta, em tokens. Opcional neste endpoint; o SDK da Anthropic sempre o envia. Um valor fora do intervalo de 1 a 65,536 é ajustado para dentro dele. Também é a quantia reservada do seu saldo enquanto a requisição é executada. | Modelos open-weight hospedados, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 |
stream | boolean | false | true envia a resposta como server-sent events. Veja Streaming abaixo. | Todos os modelos |
temperature | number | Temperatura de amostragem. Nos modelos open-weight hospedados, os valores são mantidos entre 0 e 2. | Modelos open-weight hospedados, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 | |
top_p | number | Amostragem nucleus. | Modelos open-weight hospedados | |
stop_sequences | array | Até 4 strings. A resposta termina antes da primeira que aparecer. stop_reason continua end_turn. | Modelos open-weight hospedados | |
tools | array | As ferramentas que o modelo pode chamar, cada uma como {"name", "description", "input_schema"}. Veja Ferramentas abaixo. | Todos os modelos | |
tool_choice | object | {"type": "auto"} deixa o modelo decidir, {"type": "any"} o obriga a chamar uma ferramenta, {"type": "tool", "name": "…"} o obriga a chamar essa ferramenta. | Modelos open-weight hospedados | |
thinking | object | Quanto o modelo raciocina antes de responder. Veja Thinking abaixo. | Modelos open-weight hospedados | |
web_search | boolean | false | Um acréscimo da Shannon ao formato: true permite que o modelo pesquise na web antes de responder. | shannon-1.6-*, shannon-2-*, família Shannon 3 |
Sem max_tokens, o valor é 4,096, e 65,536 em shannon-coder-1.
metadata, top_k, service_tier e marcadores cache_control nos blocos são aceitos para que o código de cliente existente rode sem alterações. Eles não mudam a resposta; o cache de prompt nos modelos open-weight hospedados é automático.
Uma resposta JSON conforme um schema é pedida com response_format em Chat Completions e com text.format em Responses. Saídas estruturadas
Uma requisição com prompt de sistema e thinking
Esta requisição envia um prompt de sistema, um orçamento de thinking, uma temperatura e uma sequência de parada. Ela usa um modelo open-weight hospedado, 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 hospedados, usage informa os tokens lidos do cache de prompt separadamente dos demais tokens de entrada.
{
"usage": {
"input_tokens": 31,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 62
}
} Prompt de sistema
system é uma string ou um array de blocos de texto na forma [{"type": "text", "text": "…"}]. Os textos dos blocos são unidos com uma quebra de linha.
Ele é aplicado pelos modelos open-weight hospedados, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro e shannon-coder-1. Com um id da família Shannon 3, coloque as instruções que precisam valer na mensagem do usuário.
Mensagens e blocos de conteúdo
Uma mensagem tem um role, user ou assistant, e um content. content é uma string ou um array de blocos.
| Bloco | Descrição | Disponível em |
|---|---|---|
{"type": "text", "text": "…"} | Texto. | Todos os modelos |
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "…"}}{"type": "image", "source": {"type": "url", "url": "…"}} | Uma imagem em uma mensagem user, em base64 ou por URL. | Família Shannon 3, shannon-1.6-lite, shannon-1.6-pro e os modelos open-weight hospedados que listam entrada de imagem |
{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} | Um documento (PDF, Word, PowerPoint ou Excel) em uma mensagem user, em base64 ou por URL. | Família Shannon 3 |
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} | Em uma mensagem assistant: uma chamada de ferramenta que o modelo fez em uma resposta anterior. | Todos os modelos |
{"type": "tool_result", "tool_use_id": "toolu_…", "content": "…"} | Em uma mensagem user: o resultado dessa chamada. content é uma string ou uma lista de blocos de texto. | Todos os modelos |
Você pode reenviar o content de uma resposta anterior como está: blocos text e tool_use são lidos, blocos thinking são ignorados.
Nos níveis Shannon, imagens e documentos são lidos da última mensagem user. Tamanhos e limites têm página própria. Imagens e arquivos
Thinking
Os modelos open-weight hospedados mapeiam thinking para um esforço de raciocínio. Sem o campo, o esforço é alto.
| Forma | budget_tokens | Efeito |
|---|---|---|
{"type": "disabled"} | Sem raciocínio. A resposta não tem bloco thinking. | |
{"type": "enabled", "budget_tokens": 2048} | ≤ 2,048 | Esforço baixo. |
{"type": "enabled", "budget_tokens": 8192} | ≤ 8,192 | Esforço médio. |
{"type": "enabled", "budget_tokens": 16000} | > 8,192 | Esforço alto. |
Um modelo que raciocina devolve seu raciocínio como um bloco {"type": "thinking", "thinking": "…"} antes do texto. Os níveis Shannon que raciocinam também o enviam.
Os esforços são descritos em uma página própria. Esforço de raciocínio
Ferramentas
Uma ferramenta é uma função que o seu código executa. Descreva cada uma com um name, uma description e um input_schema. Quando o modelo quer uma ferramenta, a resposta contém um bloco tool_use e stop_reason é tool_use.
Uma definição de ferramenta em tools:
[
{
"name": "get_weather",
"description": "Current weather for a city.",
"input_schema": {
"type": "object",
"properties": {
"city": {
"type": "string"
}
},
"required": [
"city"
]
}
}
] O content de uma resposta que a chama:
[
{
"type": "text",
"text": ""
},
{
"type": "tool_use",
"id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
"name": "get_weather",
"input": {
"city": "Paris"
}
}
] Execute a ferramenta e envie a requisição novamente com a chamada e um bloco tool_result adicionados 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 | Efeito | Aplicado por |
|---|---|---|
{"type": "auto"} | O modelo decide se chama uma ferramenta. Este é o padrão. | Todos os modelos |
{"type": "any"} | O modelo deve chamar uma das ferramentas. | Modelos open-weight hospedados |
{"type": "tool", "name": "…"} | O modelo deve chamar a ferramenta indicada. | Modelos open-weight hospedados |
Apenas ferramentas com um input_schema são lidas. A busca na web não é uma ferramenta neste endpoint: defina o campo web_search.
O loop de ferramentas é descrito por completo em uma página própria. Chamada de funções
A resposta
| Campo | Tipo | Descrição | 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 blocos da resposta, nesta ordem: thinking quando o modelo raciocinou, text e depois um tool_use por chamada de ferramenta. | Todos os modelos |
stop_reason | string | Por que a resposta terminou. Veja os valores abaixo. | Todos os modelos |
usage | object | input_tokens e output_tokens. | Todos os modelos |
sources | array | Somente em uma requisição com web_search: true cuja busca encontrou algo: os resultados entregues ao modelo, cada um com index, title e url. [1] na resposta é a entrada com index 1. Em um stream, vem com o evento message_delta. | shannon-1.6-*, shannon-2-*, família Shannon 3 |
usage.cache_read_input_tokens | integer | cache_read_input_tokens é a parte do prompt lida do cache; input_tokens é o restante. cache_creation_input_tokens é sempre 0. | Modelos open-weight hospedados |
Blocos da resposta
| Bloco | Descrição |
|---|---|
{"type": "thinking", "thinking": "…"} | O raciocínio do modelo. Não há o membro signature. |
{"type": "text", "text": "…"} | O texto da resposta. Pode estar vazio quando a resposta é uma chamada de ferramenta. |
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} | Uma chamada de ferramenta. input é um objeto JSON. Envie o resultado de volta com o mesmo id. |
stop_reason
| stop_reason | Descrição | Enviado por |
|---|---|---|
end_turn | O modelo terminou sua resposta, ou uma das suas stop_sequences apareceu. | Todos os modelos |
tool_use | A resposta contém uma ou mais chamadas de ferramenta. | Todos os modelos |
max_tokens | A resposta foi cortada no limite de saída. | Família Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1, em streams |
Streaming
Defina stream como true para receber server-sent events. Cada frame tem uma linha event: com o nome do evento e uma linha data: com um objeto JSON que repete o nome em type. Os helpers de stream do SDK da Anthropic leem esses eventos para você:
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 ordem em que chegam:
| Evento | Dados | Quando |
|---|---|---|
message_start | message | Sempre o primeiro. message contém o id, o papel, o modelo, um content vazio e um usage que começa em zero. |
content_block_start | index, content_block | Um bloco é aberto. content_block é um bloco text ou thinking vazio, ou um bloco tool_use com seu id e name. |
content_block_delta | index, delta {"type": "thinking_delta", "thinking"} | Um trecho do raciocínio, para um bloco thinking. |
content_block_delta | index, delta {"type": "text_delta", "text"} | Um trecho da resposta, para um bloco text. |
content_block_delta | index, delta {"type": "input_json_delta", "partial_json"} | Os argumentos de uma chamada de ferramenta, completos em um único delta, para um bloco tool_use. |
content_block_stop | index | O bloco com este index foi concluído. |
message_delta | delta {stop_reason, stop_sequence}, usage | O fim da resposta: delta.stop_reason e o usage da requisição. |
message_stop | Sempre o último. |
Os blocos são numerados por index na ordem em que são abertos, e um bloco é concluído antes de o próximo abrir. Leia cada bloco pelo seu tipo, não pelo número: um stream pode abrir primeiro um bloco text vazio, depois o bloco thinking, e entregar a resposta em um bloco 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 | Descrição |
|---|---|
Família Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 | Um evento ping com os dados {"type": "ping"}, a cada 15 segundos. |
| Modelos open-weight hospedados | Uma linha de comentário : keepalive, a cada 15 segundos enquanto o modelo trabalha. |
Um stream que falha
Uma falha depois que o stream começou é um evento error com o mesmo corpo de uma resposta de erro: {"type": "error", "error": {"type", "message"}}. Os eventos finais, message_delta e message_stop, ainda vêm em seguida. Trate a resposta como falha e envie a requisição novamente.
Erros
Os erros usam o corpo de erro da Anthropic: type é error, e o objeto error contém um type e uma message. A tabela lista o que este endpoint retorna com mais frequência. A lista completa, com o que tentar de novo, tem página própria. Tratamento de erros
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} | Status | Tipo | Mensagem | Quando |
|---|---|---|---|
401 | authentication_error | Missing authenticationInvalid API key | Nenhuma chave de API foi enviada, ou a chave é desconhecida ou foi revogada. |
400 | invalid_request_error | unknown model: <id> | model não é um id de modelo Shannon. |
400 | invalid_request_error | No user message provided | Níveis Shannon: a requisição não tem texto de usuário nem tools. |
400 | invalid_request_error | <id> does not accept image input | Uma imagem foi enviada a um modelo open-weight hospedado sem entrada de imagem. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | messages está ausente, ou um campo tem o tipo JSON errado. |
429 | rate_limit_error | Quota exceeded. Upgrade your plan at shannon-ai.com/plan | max_tokens é maior do que o que resta do seu saldo. |
429 | rate_limit_error | Too many requests. Retry in <n>s. | Proteção contra flood: mais de 120 requisições em um minuto na sua conta. |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | shannon-coder-1: as chamadas do Shannon Coder do seu plano para a janela atual de 4 horas foram esgotadas. |
500 | server_error | The model backend failed to answer. Please retry. | O modelo não produziu uma resposta. Envie a requisição novamente. |
502 | api_error | The model backend failed to answer. Please retry. | O modelo não produziu uma resposta. Envie a requisição novamente. |
Contagem de tokens
POST /v1/messages/count_tokens recebe o mesmo corpo de uma requisição de mensagem (model, system, messages, tools) e retorna {"input_tokens": n}: o número de tokens de entrada que seriam cobrados pela requisição. Ele conta para os modelos open-weight hospedados, é gratuito e não entra na contagem da proteção contra flood.
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 contagem tem página própria, com o endpoint de texto simples e os limites. Contagem de tokens