Formát Anthropic
POST /v1/messages prijíma request vo formáte Anthropic Messages a odpovedá v rovnakom formáte, streamovane alebo nie. Používajte ho s Anthropic SDK a s nástrojmi na ňom postavenými, napríklad Claude Code: nastavte základnú URL, použite svoj API kľúč Shannon a zadajte id modelu Shannon.
POST https://api.shannon-ai.com/v1/messages
Nasmerujte Anthropic SDK na základnú URL Shannon. SDK pridá /v1/messages a pošle váš kľúč v hlavičke 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."}]
}' Odpoveď je správa, ktorej content je zoznam blokov. Bloky hľadajte podľa ich type: keď model uvažoval, prvý blok je thinking a text nasleduje za ním.
{
"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
}
} Hlavičky
| Hlavička | Hodnota | Popis |
|---|---|---|
x-api-key | YOUR_API_KEY | Váš API kľúč. Namiesto neho sa prijíma Authorization: Bearer YOUR_API_KEY. |
content-type | application/json | Povinná. |
anthropic-version | 2023-06-01 | Prijíma sa, nie je povinná. Anthropic SDK posiela 2023-06-01; odpoveď má rovnaký formát bez ohľadu na hodnotu. |
anthropic-beta | Prijíma sa, nie je povinná. | |
x-request-id | Nepovinná. Vaše vlastné id requestu. V odpovedi sa vráti nezmenené; bez nej odpoveď nesie id z 12 hexadecimálnych znakov. |
Polia requestu
Povinné je iba messages. Stĺpec Uplatňuje uvádza modely, na ktorých pole mení odpoveď. Hostované open-weight modely sú dvanásť id zo zoznamu modelov; rodinu Shannon 3 tvoria shannon-3, shannon-3-pro, shannon-3.1 a shannon-3.1-pro. Modely a ceny
| Pole | Typ | Predvolené | Popis | Uplatňuje |
|---|---|---|---|---|
model | string | shannon-1.6-lite | Id modelu Shannon zo zoznamu modelov. Posielajte ho s každým requestom. Na veľkosti písmen nezáleží. Akýkoľvek iný názov vráti 400 unknown model, takže nástroj, ktorý posiela vlastné názvy modelov, treba nastaviť na id Shannon. | Všetky modely |
messages | array | Povinné. Konverzácia, najstaršia správa prvá, s rolami user a assistant. Pozrite Správy a bloky obsahu nižšie. | Všetky modely | |
system | string | array | Pokyny pre model: reťazec alebo pole textových blokov. Pozrite Systémový prompt nižšie. | Hostované open-weight modely, shannon-1.6-*, shannon-2-*, shannon-coder-1 | |
max_tokens | integer | 4096 | Horný limit odpovede v tokenoch. Na tomto endpointe nepovinné; Anthropic SDK ho posiela vždy. Hodnota mimo rozsahu 1 až 65,536 sa posunie do tohto rozsahu. Je to aj suma, ktorá sa počas behu requestu vyhradí zo zostatku. | Hostované open-weight modely, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 |
stream | boolean | false | true pošle odpoveď ako server-sent events. Pozrite Streamovanie nižšie. | Všetky modely |
temperature | number | Teplota vzorkovania. Na hostovaných open-weight modeloch sa hodnoty držia medzi 0 a 2. | Hostované open-weight modely, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 | |
top_p | number | Nucleus sampling. | Hostované open-weight modely | |
stop_sequences | array | Až 4 reťazce. Odpoveď sa skončí pred prvým z nich, ktorý sa objaví. stop_reason zostane end_turn. | Hostované open-weight modely | |
tools | array | Nástroje, ktoré môže model volať, každý ako {"name", "description", "input_schema"}. Pozrite Nástroje nižšie. | Všetky modely | |
tool_choice | object | {"type": "auto"} nechá rozhodnúť model, {"type": "any"} ho prinúti zavolať nástroj, {"type": "tool", "name": "…"} ho prinúti zavolať tento nástroj. | Hostované open-weight modely | |
thinking | object | Ako dlho model uvažuje, kým odpovie. Pozrite Thinking nižšie. | Hostované open-weight modely | |
web_search | boolean | false | Doplnok Shannon k formátu: true umožní modelu pred odpoveďou vyhľadávať na webe. | shannon-1.6-*, shannon-2-*, rodina Shannon 3 |
Bez max_tokens je hodnota 4,096 a na shannon-coder-1 65,536.
Značky metadata, top_k, service_tier a cache_control na blokoch sa prijímajú, aby existujúci klientsky kód bežal bez zmien. Odpoveď nemenia; prompt caching na hostovaných open-weight modeloch je automatický.
Odpoveď JSON podľa schémy sa žiada cez response_format v Chat Completions a cez text.format v Responses. Štruktúrované výstupy
Request so systémovým promptom a thinking
Tento request posiela systémový prompt, rozpočet thinking, teplotu a stop sekvenciu. Používa hostovaný open-weight model, ktorý uplatní všetky.
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?"}]
}' Na hostovaných open-weight modeloch usage hlási tokeny prečítané z prompt cache oddelene od ostatných vstupných tokenov.
{
"usage": {
"input_tokens": 31,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 62
}
} Systémový prompt
system je reťazec alebo pole textových blokov v tvare [{"type": "text", "text": "…"}]. Texty blokov sa spoja zalomením riadku.
Uplatňujú ho hostované open-weight modely, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro a shannon-coder-1. S id z rodiny Shannon 3 dajte pokyny, ktoré musia platiť, do správy používateľa.
Správy a bloky obsahu
Správa má role, user alebo assistant, a content. content je reťazec alebo pole blokov.
| Blok | Popis | Dostupné na |
|---|---|---|
{"type": "text", "text": "…"} | Text. | Všetky modely |
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "…"}}{"type": "image", "source": {"type": "url", "url": "…"}} | Obrázok v správe user, ako base64 alebo cez URL. | Rodina Shannon 3, shannon-1.6-lite, shannon-1.6-pro a hostované open-weight modely, ktoré uvádzajú obrázkový vstup |
{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} | Dokument (PDF, Word, PowerPoint alebo Excel) v správe user, ako base64 alebo cez URL. | Rodina Shannon 3 |
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} | V správe assistant: volanie nástroja, ktoré model urobil v skoršej odpovedi. | Všetky modely |
{"type": "tool_result", "tool_use_id": "toolu_…", "content": "…"} | V správe user: výsledok tohto volania. content je reťazec alebo zoznam textových blokov. | Všetky modely |
content skoršej odpovede môžete poslať späť tak, ako je: bloky text a tool_use sa čítajú, bloky thinking sa preskakujú.
Na úrovniach Shannon sa obrázky a dokumenty čítajú z poslednej správy user. Veľkosti a limity majú vlastnú stránku. Obrázky a súbory
Thinking
Hostované open-weight modely mapujú thinking na úsilie pri uvažovaní. Bez tohto poľa je úsilie vysoké.
| Forma | budget_tokens | Účinok |
|---|---|---|
{"type": "disabled"} | Bez uvažovania. Odpoveď nemá blok thinking. | |
{"type": "enabled", "budget_tokens": 2048} | ≤ 2,048 | Nízke úsilie. |
{"type": "enabled", "budget_tokens": 8192} | ≤ 8,192 | Stredné úsilie. |
{"type": "enabled", "budget_tokens": 16000} | > 8,192 | Vysoké úsilie. |
Model, ktorý uvažuje, vráti svoje uvažovanie ako blok {"type": "thinking", "thinking": "…"} pred textom. Úrovne Shannon, ktoré uvažujú, ho posielajú tiež.
Úrovne úsilia sú popísané na vlastnej stránke. Úsilie pri uvažovaní
Nástroje
Nástroj je funkcia, ktorú spúšťa váš kód. Každý popíšte pomocou name, description a input_schema. Keď model chce nástroj, odpoveď obsahuje blok tool_use a stop_reason je tool_use.
Definícia nástroja v tools:
[
{
"name": "get_weather",
"description": "Current weather for a city.",
"input_schema": {
"type": "object",
"properties": {
"city": {
"type": "string"
}
},
"required": [
"city"
]
}
}
] content odpovede, ktorá ho volá:
[
{
"type": "text",
"text": ""
},
{
"type": "tool_use",
"id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
"name": "get_weather",
"input": {
"city": "Paris"
}
}
] Spustite nástroj a potom odošlite request znova s volaním a blokom tool_result pridanými do 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 | Účinok | Uplatňuje |
|---|---|---|
{"type": "auto"} | Model sám rozhodne, či zavolá nástroj. Toto je predvolené. | Všetky modely |
{"type": "any"} | Model musí zavolať jeden z nástrojov. | Hostované open-weight modely |
{"type": "tool", "name": "…"} | Model musí zavolať pomenovaný nástroj. | Hostované open-weight modely |
Čítajú sa iba nástroje s input_schema. Webové vyhľadávanie nie je na tomto endpointe nástroj: nastavte pole web_search.
Slučka nástrojov je úplne popísaná na vlastnej stránke. Volanie funkcií
Odpoveď
| Pole | Typ | Popis | Posiela |
|---|---|---|---|
id | string | msg_ nasledované 32 hexadecimálnymi znakmi. | Všetky modely |
type | string | Vždy message. | Všetky modely |
role | string | Vždy assistant. | Všetky modely |
model | string | Kanonické id modelu, ktorý odpovedal. | Všetky modely |
content | array | Bloky odpovede v tomto poradí: thinking, keď model uvažoval, text, potom jeden tool_use na každé volanie nástroja. | Všetky modely |
stop_reason | string | Prečo odpoveď skončila. Pozrite hodnoty nižšie. | Všetky modely |
usage | object | input_tokens a output_tokens. | Všetky modely |
sources | array | Len pri requeste s web_search: true, ktorého vyhľadávanie niečo našlo: výsledky, ktoré model dostal, každý s index, title a url. [1] v odpovedi je záznam s index 1. V streame prichádza s udalosťou message_delta. | shannon-1.6-*, shannon-2-*, rodina Shannon 3 |
usage.cache_read_input_tokens | integer | cache_read_input_tokens je časť promptu prečítaná z cache; input_tokens je zvyšok. cache_creation_input_tokens je vždy 0. | Hostované open-weight modely |
Bloky odpovede
| Blok | Popis |
|---|---|
{"type": "thinking", "thinking": "…"} | Uvažovanie modelu. Člen signature neexistuje. |
{"type": "text", "text": "…"} | Text odpovede. Môže byť prázdny, keď je odpoveďou volanie nástroja. |
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} | Volanie nástroja. input je objekt JSON. Výsledok pošlite späť s rovnakým id. |
stop_reason
| stop_reason | Popis | Posiela |
|---|---|---|
end_turn | Model dokončil odpoveď, alebo sa objavila jedna z vašich stop_sequences. | Všetky modely |
tool_use | Odpoveď obsahuje jedno alebo viac volaní nástrojov. | Všetky modely |
max_tokens | Odpoveď bola odrezaná na limite výstupu. | Rodina Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1, v streamoch |
Streamovanie
Nastavte stream na true pre server-sent events. Každý frame má riadok event: s názvom udalosti a riadok data: s objektom JSON, ktorý názov opakuje v type. Stream helpery Anthropic SDK tieto udalosti čítajú za vás:
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."}]
}' Udalosti v poradí, v akom prichádzajú:
| Udalosť | Dáta | Kedy |
|---|---|---|
message_start | message | Vždy prvá. message obsahuje id, rolu, model, prázdny content a usage, ktoré začína na nule. |
content_block_start | index, content_block | Otvorí sa blok. content_block je prázdny blok text alebo thinking, alebo blok tool_use s jeho id a name. |
content_block_delta | index, delta {"type": "thinking_delta", "thinking"} | Kúsok uvažovania, pre blok thinking. |
content_block_delta | index, delta {"type": "text_delta", "text"} | Kúsok odpovede, pre blok text. |
content_block_delta | index, delta {"type": "input_json_delta", "partial_json"} | Argumenty volania nástroja, kompletné v jednej delte, pre blok tool_use. |
content_block_stop | index | Blok s týmto index je dokončený. |
message_delta | delta {stop_reason, stop_sequence}, usage | Koniec odpovede: delta.stop_reason a usage requestu. |
message_stop | Vždy posledná. |
Bloky sú číslované podľa index v poradí, v akom sa otvárajú, a jeden blok je dokončený skôr, než sa otvorí ďalší. Každý blok čítajte podľa jeho typu, nie podľa čísla: stream môže najprv otvoriť prázdny blok text, potom blok thinking a odpoveď doručiť v neskoršom bloku text.
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
| Posiela | Popis |
|---|---|
Rodina Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 | Udalosť ping s dátami {"type": "ping"} každých 15 sekúnd. |
| Hostované open-weight modely | Riadok komentára : keepalive každých 15 sekúnd, kým model pracuje. |
Stream, ktorý zlyhá
Zlyhanie po začatí streamu je udalosť error s rovnakým telom ako odpoveď s chybou: {"type": "error", "error": {"type", "message"}}. Záverečné udalosti message_delta a message_stop stále nasledujú. Odpoveď považujte za zlyhanú a odošlite request znova.
Chyby
Chyby používajú telo chyby Anthropic: type je error a objekt error obsahuje type a message. Tabuľka uvádza, čo tento endpoint vracia najčastejšie. Úplný zoznam s odporúčaním, čo opakovať, má vlastnú stránku. Spracovanie chýb
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} | Stav | Typ | Správa | Kedy |
|---|---|---|---|
401 | authentication_error | Missing authenticationInvalid API key | Nebol odoslaný žiadny API kľúč, alebo je kľúč neznámy či zrušený. |
400 | invalid_request_error | unknown model: <id> | model nie je id modelu Shannon. |
400 | invalid_request_error | No user message provided | Úrovne Shannon: request nemá žiadny text používateľa ani tools. |
400 | invalid_request_error | <id> does not accept image input | Obrázok bol odoslaný hostovanému open-weight modelu bez obrázkového vstupu. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | messages chýba alebo pole má nesprávny typ JSON. |
429 | rate_limit_error | Quota exceeded. Upgrade your plan at shannon-ai.com/plan | max_tokens je väčšie, než koľko zostáva z vášho zostatku. |
429 | rate_limit_error | Too many requests. Retry in <n>s. | Ochrana pred zahltením: viac ako 120 requestov za minútu na vašom účte. |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | shannon-coder-1: volania Shannon Coder vášho plánu pre aktuálne 4-hodinové okno sú vyčerpané. |
500 | server_error | The model backend failed to answer. Please retry. | Model nevytvoril odpoveď. Odošlite request znova. |
502 | api_error | The model backend failed to answer. Please retry. | Model nevytvoril odpoveď. Odošlite request znova. |
Počítanie tokenov
POST /v1/messages/count_tokens prijíma rovnaké telo ako request správy (model, system, messages, tools) a vracia {"input_tokens": n}: počet vstupných tokenov, ktoré by sa za request účtovali. Počíta pre hostované open-weight modely, je bezplatné a ochrana pred zahltením ho nepočíta.
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} Počítanie má vlastnú stránku s endpointom pre čistý text a s limitmi. Počítanie tokenov