Saltar ao contido
Anthropic

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)

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.

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
  }
}

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)

Nos modelos open-weight alojados, usage informa dos tokens lidos da caché de prompts por separado do resto de tokens de entrada.

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

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:

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

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)

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.

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 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

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

A contaxe ten a súa propia páxina, co endpoint de texto simple e os límites. Reconto de tokens