Ir para o conteúdo
Formato Anthropic

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)

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.

200 JSON
{
  "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)

Nos modelos open-weight hospedados, usage informa os tokens lidos do cache de prompt separadamente dos demais tokens de entrada.

200 JSON
{
  "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:

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:

200 content
[
  {
    "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:

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)

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.

200 text/event-stream
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

400 JSON
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}
Status Tipo Mensagem Quando
401 authentication_error Missing authentication
Invalid 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)

A contagem tem página própria, com o endpoint de texto simples e os limites. Contagem de tokens