Format Anthropic
POST /v1/messages primește o cerere în formatul Anthropic Messages și răspunde în același format, cu streaming sau fără. Folosește-l cu SDK-ul Anthropic și cu instrumentele construite pe el, precum Claude Code: setează URL-ul de bază, folosește cheia ta Shannon API și indică un id de model Shannon.
POST https://api.shannon-ai.com/v1/messages
Îndreaptă SDK-ul Anthropic spre URL-ul de bază Shannon. SDK-ul adaugă /v1/messages și trimite cheia ta în header-ul 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."}]
}' Răspunsul este un mesaj al cărui content este o listă de blocuri. Găsește blocurile după type: când modelul a raționat, primul bloc este thinking, iar textul vine după el.
{
"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
}
} Headere
| Header | Valoare | Descriere |
|---|---|---|
x-api-key | YOUR_API_KEY | Cheia ta API. Authorization: Bearer YOUR_API_KEY este acceptat în locul ei. |
content-type | application/json | Obligatoriu. |
anthropic-version | 2023-06-01 | Acceptat, nu este obligatoriu. SDK-ul Anthropic trimite 2023-06-01; răspunsul are același format indiferent de valoare. |
anthropic-beta | Acceptat, nu este obligatoriu. | |
x-request-id | Opțional. Propriul tău id pentru cerere. Se întoarce neschimbat în răspuns; fără el, răspunsul conține un id de 12 caractere hexazecimale. |
Câmpuri de cerere
Doar messages este obligatoriu. Coloana Aplicat de indică modelele pe care un câmp modifică răspunsul. Modelele open-weight găzduite sunt cele douăsprezece id-uri din lista de modele; familia Shannon 3 este shannon-3, shannon-3-pro, shannon-3.1 și shannon-3.1-pro. Modele și prețuri
| Câmp | Tip | Implicit | Descriere | Aplicat de |
|---|---|---|---|---|
model | string | shannon-1.6-lite | Un id de model Shannon din lista de modele. Trimite-l la fiecare cerere. Potrivirea nu ține cont de majuscule. Orice alt nume returnează 400 unknown model, deci un instrument care trimite propriile nume de modele trebuie setat pe un id Shannon. | Toate modelele |
messages | array | Obligatoriu. Conversația, cu cel mai vechi mesaj primul, cu rolurile user și assistant. Vezi Mesaje și blocuri de conținut mai jos. | Toate modelele | |
system | string | array | Instrucțiuni pentru model: un șir de caractere sau o matrice de blocuri de text. Vezi System prompt mai jos. | Modele open-weight găzduite, shannon-1.6-*, shannon-2-*, shannon-coder-1 | |
max_tokens | integer | 4096 | Limita superioară a răspunsului, în token-uri. Opțional pe acest endpoint; SDK-ul Anthropic îl trimite întotdeauna. O valoare în afara intervalului 1 – 65,536 este mutată în acel interval. Este și cantitatea rezervată din soldul tău cât timp rulează cererea. | Modele open-weight găzduite, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 |
stream | boolean | false | true trimite răspunsul ca server-sent events. Vezi Streaming mai jos. | Toate modelele |
temperature | number | Temperatura de eșantionare. Pe modelele open-weight găzduite, valorile sunt păstrate între 0 și 2. | Modele open-weight găzduite, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 | |
top_p | number | Eșantionare nucleus. | Modele open-weight găzduite | |
stop_sequences | array | Până la 4 șiruri. Răspunsul se încheie înainte de primul care apare. stop_reason rămâne end_turn. | Modele open-weight găzduite | |
tools | array | Instrumentele pe care modelul le poate apela, fiecare sub forma {"name", "description", "input_schema"}. Vezi Instrumente mai jos. | Toate modelele | |
tool_choice | object | {"type": "auto"} lasă modelul să decidă, {"type": "any"} îl obligă să apeleze un instrument, {"type": "tool", "name": "…"} îl obligă să apeleze acel instrument. | Modele open-weight găzduite | |
thinking | object | Cât raționează modelul înainte să răspundă. Vezi Gândire mai jos. | Modele open-weight găzduite | |
web_search | boolean | false | Un adaos Shannon la format: true permite modelului să caute pe web înainte de a răspunde. | shannon-1.6-*, shannon-2-*, familia Shannon 3 |
Fără max_tokens, valoarea este 4,096, iar pe shannon-coder-1 este 65,536.
Markerii metadata, top_k, service_tier și cache_control de pe blocuri sunt acceptați, astfel încât codul client existent să ruleze neschimbat. Ei nu modifică răspunsul; caching-ul de prompt pe modelele open-weight găzduite este automat.
Un răspuns JSON conform unei scheme se cere cu response_format la Chat Completions și cu text.format la Responses. Rezultate structurate
O cerere cu system prompt și gândire
Această cerere trimite un system prompt, un buget de gândire, o temperatură și o secvență de oprire. Folosește un model open-weight găzduit, care le aplică pe toate.
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?"}]
}' Pe modelele open-weight găzduite, usage raportează token-urile citite din cache-ul de prompt separat de celelalte token-uri de intrare.
{
"usage": {
"input_tokens": 31,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 62
}
} System prompt
system este un șir de caractere sau o matrice de blocuri de text de forma [{"type": "text", "text": "…"}]. Textele blocurilor sunt unite printr-o linie nouă.
Este aplicat de modelele open-weight găzduite, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro și shannon-coder-1. Cu un id din familia Shannon 3, pune instrucțiunile care trebuie respectate în mesajul utilizatorului.
Mesaje și blocuri de conținut
Un mesaj are un role, user sau assistant, și un content. content este un șir de caractere sau o matrice de blocuri.
| Bloc | Descriere | Disponibil pe |
|---|---|---|
{"type": "text", "text": "…"} | Text. | Toate modelele |
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "…"}}{"type": "image", "source": {"type": "url", "url": "…"}} | O imagine într-un mesaj user, ca base64 sau prin URL. | Familia Shannon 3, shannon-1.6-lite, shannon-1.6-pro și modelele open-weight găzduite care acceptă imagini la intrare |
{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} | Un document (PDF, Word, PowerPoint sau Excel) într-un mesaj user, ca base64 sau prin URL. | Familia Shannon 3 |
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} | Într-un mesaj assistant: un apel de instrument făcut de model într-un răspuns anterior. | Toate modelele |
{"type": "tool_result", "tool_use_id": "toolu_…", "content": "…"} | Într-un mesaj user: rezultatul acelui apel. content este un șir de caractere sau o listă de blocuri de text. | Toate modelele |
Poți trimite înapoi content al unui răspuns anterior exact așa cum este: blocurile text și tool_use sunt citite, blocurile thinking sunt ignorate.
Pe nivelurile Shannon, imaginile și documentele se citesc din ultimul mesaj user. Dimensiunile și limitele au propria pagină. Imagini și fișiere
Gândire
Modelele open-weight găzduite asociază thinking cu un efort de raționament. Fără acest câmp, efortul este ridicat.
| Formă | budget_tokens | Efect |
|---|---|---|
{"type": "disabled"} | Fără raționament. Răspunsul nu are bloc thinking. | |
{"type": "enabled", "budget_tokens": 2048} | ≤ 2,048 | Efort scăzut. |
{"type": "enabled", "budget_tokens": 8192} | ≤ 8,192 | Efort mediu. |
{"type": "enabled", "budget_tokens": 16000} | > 8,192 | Efort ridicat. |
Un model care raționează returnează raționamentul ca bloc {"type": "thinking", "thinking": "…"} înaintea textului. Nivelurile Shannon care raționează îl trimit și ele.
Nivelurile de efort sunt descrise pe propria pagină. Efort de raționament
Instrumente
Un instrument este o funcție pe care o rulează codul tău. Descrie fiecare instrument cu un name, o description și un input_schema. Când modelul dorește un instrument, răspunsul conține un bloc tool_use, iar stop_reason este tool_use.
O definiție de instrument în tools:
[
{
"name": "get_weather",
"description": "Current weather for a city.",
"input_schema": {
"type": "object",
"properties": {
"city": {
"type": "string"
}
},
"required": [
"city"
]
}
}
] content al unui răspuns care îl apelează:
[
{
"type": "text",
"text": ""
},
{
"type": "tool_use",
"id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
"name": "get_weather",
"input": {
"city": "Paris"
}
}
] Rulează instrumentul, apoi trimite din nou cererea cu apelul și cu un bloc tool_result adăugate în 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
| Formă | Efect | Aplicat de |
|---|---|---|
{"type": "auto"} | Modelul decide dacă apelează un instrument. Aceasta este valoarea implicită. | Toate modelele |
{"type": "any"} | Modelul trebuie să apeleze unul dintre instrumente. | Modele open-weight găzduite |
{"type": "tool", "name": "…"} | Modelul trebuie să apeleze instrumentul indicat. | Modele open-weight găzduite |
Sunt citite doar instrumentele cu un input_schema. Căutarea web nu este un instrument pe acest endpoint: setează câmpul web_search.
Bucla instrumentelor este descrisă complet pe propria pagină. Apelare funcții
Răspunsul
| Câmp | Tip | Descriere | Trimis de |
|---|---|---|---|
id | string | msg_ urmat de 32 de caractere hexazecimale. | Toate modelele |
type | string | Întotdeauna message. | Toate modelele |
role | string | Întotdeauna assistant. | Toate modelele |
model | string | Id-ul canonic al modelului care a răspuns. | Toate modelele |
content | array | Blocurile răspunsului, în această ordine: thinking când modelul a raționat, text, apoi câte un tool_use pentru fiecare apel de instrument. | Toate modelele |
stop_reason | string | Motivul pentru care s-a încheiat răspunsul. Vezi valorile de mai jos. | Toate modelele |
usage | object | input_tokens și output_tokens. | Toate modelele |
sources | array | Doar la o cerere cu web_search: true a cărei căutare a găsit ceva: rezultatele date modelului, fiecare cu index, title și url. [1] din răspuns este intrarea cu index 1. Într-un stream vine cu evenimentul message_delta. | shannon-1.6-*, shannon-2-*, familia Shannon 3 |
usage.cache_read_input_tokens | integer | cache_read_input_tokens este partea din prompt citită din cache; input_tokens este restul. cache_creation_input_tokens este întotdeauna 0. | Modele open-weight găzduite |
Blocurile răspunsului
| Bloc | Descriere |
|---|---|
{"type": "thinking", "thinking": "…"} | Raționamentul modelului. Nu există membrul signature. |
{"type": "text", "text": "…"} | Textul răspunsului. Poate fi gol atunci când răspunsul este un apel de instrument. |
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} | Un apel de instrument. input este un obiect JSON. Trimite rezultatul înapoi cu același id. |
stop_reason
| stop_reason | Descriere | Trimis de |
|---|---|---|
end_turn | Modelul și-a încheiat răspunsul sau a apărut una dintre stop_sequences ale tale. | Toate modelele |
tool_use | Răspunsul conține unul sau mai multe apeluri de instrument. | Toate modelele |
max_tokens | Răspunsul a fost tăiat la limita de ieșire. | Familia Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1, în stream-uri |
Streaming
Setează stream la true pentru server-sent events. Fiecare cadru are o linie event: cu numele evenimentului și o linie data: cu un obiect JSON care repetă numele în type. Funcțiile helper de stream ale SDK-ului Anthropic citesc aceste evenimente pentru tine:
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."}]
}' Evenimentele, în ordinea în care sosesc:
| Eveniment | Date | Când |
|---|---|---|
message_start | message | Întotdeauna primul. message conține id-ul, rolul, modelul, un content gol și un usage care pornește de la zero. |
content_block_start | index, content_block | Se deschide un bloc. content_block este un bloc text sau thinking gol ori un bloc tool_use cu id și name. |
content_block_delta | index, delta {"type": "thinking_delta", "thinking"} | O bucată din raționament, pentru un bloc thinking. |
content_block_delta | index, delta {"type": "text_delta", "text"} | O bucată din răspuns, pentru un bloc text. |
content_block_delta | index, delta {"type": "input_json_delta", "partial_json"} | Argumentele unui apel de instrument, complete într-un singur delta, pentru un bloc tool_use. |
content_block_stop | index | Blocul cu acest index este complet. |
message_delta | delta {stop_reason, stop_sequence}, usage | Sfârșitul răspunsului: delta.stop_reason și usage al cererii. |
message_stop | Întotdeauna ultimul. |
Blocurile sunt numerotate prin index în ordinea în care se deschid, iar un bloc este complet înainte să se deschidă următorul. Citește fiecare bloc după tipul lui, nu după număr: un stream poate deschide mai întâi un bloc text gol, apoi blocul thinking, și poate livra răspunsul într-un bloc text ulterior.
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
| Trimis de | Descriere |
|---|---|
Familia Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 | Un eveniment ping cu datele {"type": "ping"}, la fiecare 15 secunde. |
| Modele open-weight găzduite | O linie de comentariu : keepalive, la fiecare 15 secunde cât timp lucrează modelul. |
Un stream care eșuează
O eroare după ce stream-ul a început este un eveniment error cu același corp ca un răspuns de eroare: {"type": "error", "error": {"type", "message"}}. Evenimentele de încheiere, message_delta și message_stop, urmează totuși. Tratează răspunsul ca eșuat și trimite cererea din nou.
Erori
Erorile folosesc corpul de eroare Anthropic: type este error, iar obiectul error conține un type și un message. Tabelul listează ce returnează cel mai des acest endpoint. Lista completă, cu ce merită reîncercat, are propria pagină. Gestionare erori
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} | Stare | Tip | Mesaj | Când |
|---|---|---|---|
401 | authentication_error | Missing authenticationInvalid API key | Nu a fost trimisă nicio cheie API sau cheia este necunoscută ori revocată. |
400 | invalid_request_error | unknown model: <id> | model nu este un id de model Shannon. |
400 | invalid_request_error | No user message provided | Niveluri Shannon: cererea nu are text de la utilizator și nici tools. |
400 | invalid_request_error | <id> does not accept image input | O imagine a fost trimisă unui model open-weight găzduit care nu acceptă imagini la intrare. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | messages lipsește sau un câmp are tipul JSON greșit. |
429 | rate_limit_error | Quota exceeded. Upgrade your plan at shannon-ai.com/plan | max_tokens este mai mare decât ce a rămas din soldul tău. |
429 | rate_limit_error | Too many requests. Retry in <n>s. | Protecție anti-flood: mai mult de 120 de cereri într-un minut pe contul tău. |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | shannon-coder-1: apelurile Shannon Coder ale planului tău pentru fereastra curentă de 4 ore au fost consumate. |
500 | server_error | The model backend failed to answer. Please retry. | Modelul nu a produs un răspuns. Trimite cererea din nou. |
502 | api_error | The model backend failed to answer. Please retry. | Modelul nu a produs un răspuns. Trimite cererea din nou. |
Numărarea token-urilor
POST /v1/messages/count_tokens primește același corp ca o cerere de mesaj (model, system, messages, tools) și returnează {"input_tokens": n}: numărul de token-uri de intrare care ar fi taxate pentru cerere. Funcționează pentru modelele open-weight găzduite, este gratuit și nu este numărat de protecția anti-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} Numărarea are propria pagină, cu endpoint-ul pentru text simplu și limitele. Numărarea token-urilor