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) 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."}]
}' 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.
{
"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) 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?"}]
}' Als models open-weight hostejats, usage informa dels tokens llegits de la cache del prompt per separat dels altres tokens d'entrada.
{
"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:
[
{
"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:
[
{
"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:
[
{
"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) 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."}]
}' 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.
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
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} | Estat | Tipus | Missatge | Quan |
|---|---|---|---|
401 | authentication_error | Missing authenticationInvalid 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) 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} El recompte té la seva pròpia pàgina, amb l'endpoint de text pla i els límits. Recompte de tokens