Salta al contingut
Anthropic

Anthropic

POST /v1/messages accepta una sol·licitud en el format Anthropic Messages i respon en el mateix format, amb streaming o sense. Fes-lo servir amb l'SDK d'Anthropic i amb eines basades en ell, com Claude Code: defineix la URL base, fes servir la teva clau API de Shannon i indica un id de model Shannon.

POST https://api.shannon-ai.com/v1/messages

Apunta l'SDK d'Anthropic a la URL base de Shannon. L'SDK afegeix /v1/messages i envia la teva clau a la capçalera 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)

La resposta és un missatge el content del qual és una llista de blocs. Troba els blocs pel seu type: quan el model ha raonat, el primer bloc és thinking i el text ve després.

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

Capçaleres

Capçalera Valor Descripció
x-api-key YOUR_API_KEY La teva clau API. En lloc seu s'accepta Authorization: Bearer YOUR_API_KEY.
content-type application/json Obligatori.
anthropic-version 2023-06-01 S'accepta, no és obligatori. L'SDK d'Anthropic envia 2023-06-01; la resposta té el mateix format sigui quin sigui el valor.
anthropic-beta S'accepta, no és obligatori.
x-request-id Opcional. El teu propi id per a la sol·licitud. Torna sense canvis a la resposta; sense ell, la resposta porta un id de 12 caràcters hexadecimals.

Camps de la sol·licitud

Només messages és obligatori. La columna S'aplica a indica els models en què un camp canvia la resposta. Els models open-weight hostejats són els dotze ids de la llista de models; la família Shannon 3 és shannon-3, shannon-3-pro, shannon-3.1 i shannon-3.1-pro. Models i preus

Camp Tipus Per defecte Descripció S'aplica a
model string shannon-1.6-lite Un id de model Shannon de la llista de models. Envia'l a cada sol·licitud. La coincidència no distingeix majúscules i minúscules. Qualsevol altre nom retorna 400 unknown model, de manera que una eina que envia els seus propis noms de model s'ha de configurar amb un id Shannon. Tots els models
messages array Obligatori. La conversa, amb el missatge més antic primer, amb els rols user i assistant. Vegeu Missatges i blocs de contingut més avall. Tots els models
system string | array Instruccions per al model: una cadena o una matriu de blocs de text. Vegeu Prompt de sistema més avall. Models open-weight hostejats, shannon-1.6-*, shannon-2-*, shannon-coder-1
max_tokens integer 4096 Límit superior de la resposta, en tokens. Opcional en aquest endpoint; l'SDK d'Anthropic sempre l'envia. Un valor fora de l'interval d'1 a 65,536 es porta a aquest interval. També és la quantitat que es reserva del teu saldo mentre la sol·licitud s'executa. Models open-weight hostejats, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
stream boolean false true envia la resposta com a server-sent events. Vegeu Streaming més avall. Tots els models
temperature number Temperatura de mostreig. Als models open-weight hostejats els valors es mantenen entre 0 i 2. Models open-weight hostejats, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
top_p number Mostreig de nucli. Models open-weight hostejats
stop_sequences array Fins a 4 cadenes. La resposta acaba abans de la primera que aparegui. stop_reason continua sent end_turn. Models open-weight hostejats
tools array Les eines que el model pot cridar, cadascuna com a {"name", "description", "input_schema"}. Vegeu Eines més avall. Tots els models
tool_choice object {"type": "auto"} deixa que el model decideixi, {"type": "any"} l'obliga a cridar una eina, {"type": "tool", "name": "…"} l'obliga a cridar aquesta eina. Models open-weight hostejats
thinking object Quant raona el model abans de respondre. Vegeu Thinking més avall. Models open-weight hostejats
web_search boolean false Un afegit de Shannon al format: true deixa que el model cerqui al web abans de respondre. shannon-1.6-*, shannon-2-*, família Shannon 3

Sense max_tokens el valor és 4,096, i 65,536 a shannon-coder-1.

S'accepten metadata, top_k, service_tier i els marcadors cache_control als blocs perquè el codi de client existent funcioni sense canvis. No canvien la resposta; el prompt caching als models open-weight hostejats és automàtic.

Una resposta JSON segons un esquema es demana amb response_format a Chat Completions i amb text.format a Responses. Sortides estructurades

Una sol·licitud amb prompt de sistema i thinking

Aquesta sol·licitud envia un prompt de sistema, un pressupost de thinking, una temperatura i una seqüència d'aturada. Fa servir un model open-weight hostejat, que els aplica tots.

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)

Als models open-weight hostejats, usage informa dels tokens llegits de la cache del prompt per separat dels altres tokens d'entrada.

200 JSON
{
  "usage": {
    "input_tokens": 31,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "output_tokens": 62
  }
}

Prompt de sistema

system és una cadena o una matriu de blocs de text amb la forma [{"type": "text", "text": "…"}]. Els textos dels blocs s'uneixen amb un salt de línia.

L'apliquen els models open-weight hostejats, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro i shannon-coder-1. Amb un id de la família Shannon 3, posa les instruccions que s'han de complir al missatge de l'usuari.

Missatges i blocs de contingut

Un missatge té un role, user o assistant, i un content. content és una cadena o una matriu de blocs.

Bloc Descripció Disponible a
{"type": "text", "text": "…"} Text. Tots els models
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "…"}}
{"type": "image", "source": {"type": "url", "url": "…"}}
Una imatge en un missatge user, en base64 o per URL. Família Shannon 3, shannon-1.6-lite, shannon-1.6-pro i els models open-weight hostejats que admeten entrada d'imatge
{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} Un document (PDF, Word, PowerPoint o Excel) en un missatge user, en base64 o per URL. Família Shannon 3
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} En un missatge assistant: una crida d'eina que el model va fer en una resposta anterior. Tots els models
{"type": "tool_result", "tool_use_id": "toolu_…", "content": "…"} En un missatge user: el resultat d'aquesta crida. content és una cadena o una llista de blocs de text. Tots els models

Pots tornar a enviar tal qual el content d'una resposta anterior: els blocs text i tool_use es llegeixen, els blocs thinking s'ometen.

Als nivells Shannon, les imatges i els documents es llegeixen de l'últim missatge user. Les mides i els límits tenen la seva pròpia pàgina. Imatges i fitxers

Thinking

Els models open-weight hostejats relacionen thinking amb un esforç de raonament. Sense el camp, l'esforç és alt.

Forma budget_tokens Efecte
{"type": "disabled"} Sense raonament. La resposta no té cap bloc thinking.
{"type": "enabled", "budget_tokens": 2048} ≤ 2,048 Esforç baix.
{"type": "enabled", "budget_tokens": 8192} ≤ 8,192 Esforç mitjà.
{"type": "enabled", "budget_tokens": 16000} > 8,192 Esforç alt.

Un model que raona retorna el seu raonament com a bloc {"type": "thinking", "thinking": "…"} davant del text. Els nivells Shannon que raonen també l'envien.

Els esforços es descriuen a la seva pròpia pàgina. Esforç de raonament

Eines

Una eina és una funció que executa el teu codi. Descriu-les cadascuna amb un name, una description i un input_schema. Quan el model vol una eina, la resposta conté un bloc tool_use i stop_reason és tool_use.

Una definició d'eina a tools:

tools
[
  {
    "name": "get_weather",
    "description": "Current weather for a city.",
    "input_schema": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string"
        }
      },
      "required": [
        "city"
      ]
    }
  }
]

El content d'una resposta que la crida:

200 content
[
  {
    "type": "text",
    "text": ""
  },
  {
    "type": "tool_use",
    "id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "name": "get_weather",
    "input": {
      "city": "Paris"
    }
  }
]

Executa l'eina i torna a enviar la sol·licitud amb la crida i un bloc tool_result afegits 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 Efecte S'aplica a
{"type": "auto"} El model decideix si crida una eina. Aquest és el valor per defecte. Tots els models
{"type": "any"} El model ha de cridar una de les eines. Models open-weight hostejats
{"type": "tool", "name": "…"} El model ha de cridar l'eina indicada. Models open-weight hostejats

Només es llegeixen les eines amb un input_schema. La cerca web no és una eina en aquest endpoint: defineix el camp web_search.

El bucle d'eines es descriu completament a la seva pròpia pàgina. Crida de funcions

La resposta

Camp Tipus Descripció Enviat per
id string msg_ seguit de 32 caràcters hexadecimals. Tots els models
type string Sempre message. Tots els models
role string Sempre assistant. Tots els models
model string L'id canònic del model que ha respost. Tots els models
content array Els blocs de la resposta, en aquest ordre: thinking quan el model ha raonat, text i després un tool_use per cada crida d'eina. Tots els models
stop_reason string Per què ha acabat la resposta. Vegeu els valors més avall. Tots els models
usage object input_tokens i output_tokens. Tots els models
sources array Només en una sol·licitud amb web_search: true la cerca de la qual ha trobat alguna cosa: els resultats que s'han donat al model, cadascun amb index, title i url. [1] a la resposta és l'entrada amb index 1. En un stream arriba amb l'esdeveniment message_delta. shannon-1.6-*, shannon-2-*, família Shannon 3
usage.cache_read_input_tokens integer cache_read_input_tokens és la part del prompt llegida de la cache; input_tokens és la resta. cache_creation_input_tokens sempre és 0. Models open-weight hostejats

Blocs de la resposta

Bloc Descripció
{"type": "thinking", "thinking": "…"} El raonament del model. No hi ha cap membre signature.
{"type": "text", "text": "…"} El text de la resposta. Pot estar buit quan la resposta és una crida d'eina.
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} Una crida d'eina. input és un objecte JSON. Torna a enviar el resultat amb el mateix id.

stop_reason

stop_reason Descripció Enviat per
end_turn El model ha acabat la seva resposta, o ha aparegut una de les teves stop_sequences. Tots els models
tool_use La resposta conté una o més crides d'eina. Tots els models
max_tokens La resposta s'ha tallat al límit de sortida. Família Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1, en streams

Streaming

Defineix stream a true per rebre server-sent events. Cada fragment té una línia event: amb el nom de l'esdeveniment i una línia data: amb un objecte JSON que repeteix el nom a type. Els ajudants de stream de l'SDK d'Anthropic llegeixen aquests esdeveniments per tu:

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)

Els esdeveniments, en l'ordre en què arriben:

Esdeveniment Dades Quan
message_start message Sempre el primer. message conté l'id, el rol, el model, un content buit i un usage que comença a zero.
content_block_start index, content_block S'obre un bloc. content_block és un bloc text o thinking buit, o un bloc tool_use amb el seu id i name.
content_block_delta index, delta {"type": "thinking_delta", "thinking"} Un tros del raonament, per a un bloc thinking.
content_block_delta index, delta {"type": "text_delta", "text"} Un tros de la resposta, per a un bloc text.
content_block_delta index, delta {"type": "input_json_delta", "partial_json"} Els arguments d'una crida d'eina, complets en un sol delta, per a un bloc tool_use.
content_block_stop index El bloc amb aquest index està complet.
message_delta delta {stop_reason, stop_sequence}, usage El final de la resposta: delta.stop_reason i l'usage de la sol·licitud.
message_stop Sempre l'últim.

Els blocs es numeren amb index segons l'ordre en què s'obren, i un bloc es completa abans que s'obri el següent. Llegeix cada bloc pel seu tipus, no pel seu número: un stream pot obrir primer un bloc text buit, després el bloc thinking, i lliurar la resposta en un bloc 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

Enviat per Descripció
Família Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 Un esdeveniment ping amb les dades {"type": "ping"}, cada 15 segons.
Models open-weight hostejats Una línia de comentari : keepalive, cada 15 segons mentre el model treballa.

Un stream que falla

Un error després d'haver començat el stream és un esdeveniment error amb el mateix cos que una resposta d'error: {"type": "error", "error": {"type", "message"}}. Els esdeveniments de tancament, message_delta i message_stop, continuen arribant. Considera que la resposta ha fallat i torna a enviar la sol·licitud.

Errors

Els errors fan servir el cos d'error d'Anthropic: type és error, i l'objecte error conté un type i un message. La taula llista el que aquest endpoint retorna més sovint. La llista completa, amb què cal tornar a provar, té la seva pròpia pàgina. Gestió d’errors

400 JSON
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}
Estat Tipus Missatge Quan
401 authentication_error Missing authentication
Invalid API key
No s'ha enviat cap clau API, o la clau és desconeguda o està revocada.
400 invalid_request_error unknown model: <id> model no és un id de model Shannon.
400 invalid_request_error No user message provided Nivells Shannon: la sol·licitud no té text d'usuari ni tools.
400 invalid_request_error <id> does not accept image input S'ha enviat una imatge a un model open-weight hostejat sense entrada d'imatge.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … Falta messages, o un camp té un tipus JSON incorrecte.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan max_tokens és més gran que el que queda del teu saldo.
429 rate_limit_error Too many requests. Retry in <n>s. Protecció contra inundació: més de 120 sol·licituds en un minut al teu compte.
429 rate_limit_error Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan shannon-coder-1: les crides de Shannon Coder del teu pla per a la finestra actual de 4 hores s'han esgotat.
500 server_error The model backend failed to answer. Please retry. El model no ha produït cap resposta. Torna a enviar la sol·licitud.
502 api_error The model backend failed to answer. Please retry. El model no ha produït cap resposta. Torna a enviar la sol·licitud.

Comptar tokens

POST /v1/messages/count_tokens accepta el mateix cos que una sol·licitud de missatge (model, system, messages, tools) i retorna {"input_tokens": n}: el nombre de tokens d'entrada que se cobrarien per la sol·licitud. Compta per als models open-weight hostejats, és gratuït i la protecció contra inundació no el compta.

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)

El recompte té la seva pròpia pàgina, amb l'endpoint de text pla i els límits. Recompte de tokens