Přeskočit na obsah
Formát Anthropic

Formát Anthropic

POST /v1/messages přijímá požadavek ve formátu Anthropic Messages a odpovídá ve stejném formátu, streamovaně i nestreamovaně. Použijte jej s Anthropic SDK a s nástroji na něm postavenými, jako je Claude Code: nastavte základní URL, použijte svůj API klíč Shannon a uveďte id modelu Shannon.

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

Nasměrujte Anthropic SDK na základní URL Shannon. SDK přidá /v1/messages a pošle váš klíč v hlavičce 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)

Odpověď je zpráva, jejíž content je seznam bloků. Bloky poznáte podle type: když model uvažoval, první blok je thinking a text následuje za ním.

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

Hlavičky

Hlavička Hodnota Popis
x-api-key YOUR_API_KEY Váš API klíč. Místo něj se přijímá Authorization: Bearer YOUR_API_KEY.
content-type application/json Povinná.
anthropic-version 2023-06-01 Přijímá se, není povinná. Anthropic SDK posílá 2023-06-01; odpověď má stejný formát bez ohledu na hodnotu.
anthropic-beta Přijímá se, není povinná.
x-request-id Volitelná. Vaše vlastní id požadavku. Vrátí se v odpovědi beze změny; bez ní nese odpověď id o 12 hexadecimálních znacích.

Pole požadavku

Povinné je pouze messages. Sloupec Uplatňují uvádí modely, u nichž pole mění odpověď. Hostované modely s otevřenými váhami je dvanáct id ze seznamu modelů; rodina Shannon 3 je shannon-3, shannon-3-pro, shannon-3.1 a shannon-3.1-pro. Modely a ceny

Pole Typ Výchozí Popis Uplatňují
model string shannon-1.6-lite Id modelu Shannon ze seznamu modelů. Posílejte jej s každým požadavkem. Porovnání nerozlišuje velikost písmen. Jakýkoli jiný název vrátí 400 unknown model, takže nástroj, který posílá vlastní názvy modelů, je třeba nastavit na id Shannon. Všechny modely
messages array Povinné. Konverzace, nejstarší zpráva první, s rolemi user a assistant. Viz Zprávy a bloky obsahu níže. Všechny modely
system string | array Instrukce pro model: řetězec nebo pole textových bloků. Viz Systémový prompt níže. Hostované modely s otevřenými váhami, shannon-1.6-*, shannon-2-*, shannon-coder-1
max_tokens integer 4096 Horní limit odpovědi v tokenech. Na tomto endpointu volitelné; Anthropic SDK jej posílá vždy. Hodnota mimo rozsah 1 až 65,536 se posune do tohoto rozsahu. Je to také částka, která se vašemu zůstatku vyhradí po dobu běhu požadavku. Hostované modely s otevřenými váhami, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
stream boolean false true odešle odpověď jako server-sent events. Viz Streamování níže. Všechny modely
temperature number Teplota vzorkování. U hostovaných modelů s otevřenými váhami se hodnoty drží mezi 0 a 2. Hostované modely s otevřenými váhami, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
top_p number Nucleus sampling. Hostované modely s otevřenými váhami
stop_sequences array Až 4 řetězce. Odpověď skončí před prvním z nich, který se objeví. stop_reason zůstává end_turn. Hostované modely s otevřenými váhami
tools array Nástroje, které model smí volat, každý jako {"name", "description", "input_schema"}. Viz Nástroje níže. Všechny modely
tool_choice object {"type": "auto"} nechá rozhodnout model, {"type": "any"} jej přiměje zavolat nástroj, {"type": "tool", "name": "…"} jej přiměje zavolat daný nástroj. Hostované modely s otevřenými váhami
thinking object Kolik model uvažuje, než odpoví. Viz Thinking níže. Hostované modely s otevřenými váhami
web_search boolean false Doplněk Shannon k tomuto formátu: true umožní modelu před odpovědí vyhledávat na webu. shannon-1.6-*, shannon-2-*, rodina Shannon 3

Bez max_tokens je hodnota 4,096 a u shannon-coder-1 65,536.

Značky metadata, top_k, service_tier a cache_control na blocích jsou přijímány, aby stávající klientský kód běžel beze změny. Odpověď neovlivňují; caching promptů u hostovaných modelů s otevřenými váhami je automatický.

Odpověď JSON podle schématu se vyžaduje pomocí response_format u Chat Completions a pomocí text.format u Responses. Strukturované výstupy

Požadavek se systémovým promptem a thinking

Tento požadavek posílá systémový prompt, rozpočet thinking, teplotu a zastavovací sekvenci. Používá hostovaný model s otevřenými váhami, který uplatní všechny.

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)

U hostovaných modelů s otevřenými váhami usage hlásí tokeny přečtené z cache promptů odděleně od ostatních vstupních tokenů.

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

Systémový prompt

system je řetězec nebo pole textových bloků ve tvaru [{"type": "text", "text": "…"}]. Texty bloků se spojí zalomením řádku.

Uplatňují jej hostované modely s otevřenými váhami, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro a shannon-coder-1. U id z rodiny Shannon 3 dejte instrukce, které musí platit, do zprávy uživatele.

Zprávy a bloky obsahu

Zpráva má role, tedy user nebo assistant, a content. content je řetězec nebo pole bloků.

Blok Popis Dostupné na
{"type": "text", "text": "…"} Text. Všechny modely
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "…"}}
{"type": "image", "source": {"type": "url", "url": "…"}}
Obrázek ve zprávě user, jako base64 nebo pomocí URL. Rodina Shannon 3, shannon-1.6-lite, shannon-1.6-pro a hostované modely s otevřenými váhami, které uvádějí obrázkový vstup
{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} Dokument (PDF, Word, PowerPoint nebo Excel) ve zprávě user, jako base64 nebo pomocí URL. Rodina Shannon 3
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} Ve zprávě assistant: volání nástroje, které model provedl v dřívější odpovědi. Všechny modely
{"type": "tool_result", "tool_use_id": "toolu_…", "content": "…"} Ve zprávě user: výsledek tohoto volání. content je řetězec nebo seznam textových bloků. Všechny modely

content dřívější odpovědi můžete poslat zpět beze změny: bloky text a tool_use se čtou, bloky thinking se přeskakují.

Na úrovních Shannon se obrázky a dokumenty čtou z poslední zprávy user. Velikosti a limity mají vlastní stránku. Obrázky a soubory

Thinking

Hostované modely s otevřenými váhami převádějí thinking na úsilí uvažování. Bez tohoto pole je úsilí vysoké.

Forma budget_tokens Účinek
{"type": "disabled"} Bez uvažování. Odpověď nemá blok thinking.
{"type": "enabled", "budget_tokens": 2048} ≤ 2,048 Nízké úsilí.
{"type": "enabled", "budget_tokens": 8192} ≤ 8,192 Střední úsilí.
{"type": "enabled", "budget_tokens": 16000} > 8,192 Vysoké úsilí.

Model, který uvažuje, vrací své uvažování jako blok {"type": "thinking", "thinking": "…"} před textem. Úrovně Shannon, které uvažují, jej posílají také.

Úrovně úsilí jsou popsány na vlastní stránce. Úsilí uvažování

Nástroje

Nástroj je funkce, kterou spouští váš kód. Každý popište pomocí name, description a input_schema. Když model chce nástroj, odpověď obsahuje blok tool_use a stop_reason je tool_use.

Definice nástroje v tools:

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

content odpovědi, která jej volá:

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

Spusťte nástroj a pak odešlete požadavek znovu s voláním a blokem tool_result přidanými do 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 Účinek Uplatňují
{"type": "auto"} Model sám rozhodne, zda zavolá nástroj. Toto je výchozí hodnota. Všechny modely
{"type": "any"} Model musí zavolat jeden z nástrojů. Hostované modely s otevřenými váhami
{"type": "tool", "name": "…"} Model musí zavolat pojmenovaný nástroj. Hostované modely s otevřenými váhami

Čtou se pouze nástroje s input_schema. Vyhledávání na webu na tomto endpointu není nástroj: nastavte pole web_search.

Smyčka nástrojů je popsána celá na vlastní stránce. Volání funkcí

Odpověď

Pole Typ Popis Odesílá
id string msg_ následované 32 hexadecimálními znaky. Všechny modely
type string Vždy message. Všechny modely
role string Vždy assistant. Všechny modely
model string Kanonické id modelu, který odpověděl. Všechny modely
content array Bloky odpovědi v tomto pořadí: thinking, pokud model uvažoval, text, potom jeden tool_use na každé volání nástroje. Všechny modely
stop_reason string Proč odpověď skončila. Viz hodnoty níže. Všechny modely
usage object input_tokens a output_tokens. Všechny modely
sources array Jen u požadavku s web_search: true, jehož vyhledávání něco našlo: výsledky, které model dostal, každý s index, title a url. [1] v odpovědi je záznam s index 1. Ve streamu přichází s událostí message_delta. shannon-1.6-*, shannon-2-*, rodina Shannon 3
usage.cache_read_input_tokens integer cache_read_input_tokens je část promptu přečtená z cache; input_tokens je zbytek. cache_creation_input_tokens je vždy 0. Hostované modely s otevřenými váhami

Bloky odpovědi

Blok Popis
{"type": "thinking", "thinking": "…"} Uvažování modelu. Člen signature neexistuje.
{"type": "text", "text": "…"} Text odpovědi. Může být prázdný, když je odpovědí volání nástroje.
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} Volání nástroje. input je objekt JSON. Výsledek pošlete zpět se stejným id.

stop_reason

stop_reason Popis Odesílá
end_turn Model dokončil odpověď, nebo se objevila některá z vašich stop_sequences. Všechny modely
tool_use Odpověď obsahuje jedno nebo více volání nástrojů. Všechny modely
max_tokens Odpověď byla useknuta na výstupním limitu. Rodina Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1, ve streamech

Streamování

Nastavte stream na true pro server-sent events. Každý rámec má řádek event: s názvem události a řádek data: s objektem JSON, který název opakuje v type. Stream helpery Anthropic SDK tyto události čtou 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)

Události v pořadí, v jakém přicházejí:

Událost Data Kdy
message_start message Vždy první. message obsahuje id, roli, model, prázdný content a usage, které začíná na nule.
content_block_start index, content_block Blok se otevírá. content_block je prázdný blok text nebo thinking, nebo blok tool_use s id a name.
content_block_delta index, delta {"type": "thinking_delta", "thinking"} Kus uvažování, pro blok thinking.
content_block_delta index, delta {"type": "text_delta", "text"} Kus odpovědi, pro blok text.
content_block_delta index, delta {"type": "input_json_delta", "partial_json"} Argumenty volání nástroje, kompletní v jedné deltě, pro blok tool_use.
content_block_stop index Blok s tímto index je dokončen.
message_delta delta {stop_reason, stop_sequence}, usage Konec odpovědi: delta.stop_reason a usage požadavku.
message_stop Vždy poslední.

Bloky se číslují pomocí index v pořadí, v jakém se otevírají, a jeden blok je dokončen dřív, než se otevře další. Každý blok čtěte podle jeho typu, ne podle čísla: stream může nejprve otevřít prázdný blok text, pak blok thinking a odpověď doručit v pozdějším bloku text.

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

Odesílá Popis
Rodina Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 Událost ping s daty {"type": "ping"}, každých 15 sekund.
Hostované modely s otevřenými váhami Řádek komentáře : keepalive, každých 15 sekund, dokud model pracuje.

Stream, který selže

Selhání po zahájení streamu je událost error se stejným tělem jako chybová odpověď: {"type": "error", "error": {"type", "message"}}. Závěrečné události message_delta a message_stop přesto následují. Odpověď považujte za neúspěšnou a odešlete požadavek znovu.

Chyby

Chyby používají tělo chyby Anthropic: type je error a objekt error obsahuje type a message. Tabulka uvádí, co tento endpoint vrací nejčastěji. Úplný seznam, včetně toho, co opakovat, má vlastní stránku. Zpracování chyb

400 JSON
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}
Stav Typ Zpráva Kdy
401 authentication_error Missing authentication
Invalid API key
Nebyl odeslán žádný API klíč, nebo je klíč neznámý či zrušený.
400 invalid_request_error unknown model: <id> model není id modelu Shannon.
400 invalid_request_error No user message provided Úrovně Shannon: požadavek neobsahuje žádný uživatelský text ani tools.
400 invalid_request_error <id> does not accept image input Obrázek byl odeslán hostovanému modelu s otevřenými váhami bez obrázkového vstupu.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … Chybí messages, nebo má některé pole špatný typ JSON.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan max_tokens je větší, než kolik zbývá z vašeho zůstatku.
429 rate_limit_error Too many requests. Retry in <n>s. Ochrana proti zahlcení: více než 120 požadavků za jednu minutu na vašem účtu.
429 rate_limit_error Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan shannon-coder-1: volání Shannon Coder vašeho plánu pro aktuální 4hodinové okno jsou vyčerpána.
500 server_error The model backend failed to answer. Please retry. Model nevytvořil odpověď. Odešlete požadavek znovu.
502 api_error The model backend failed to answer. Please retry. Model nevytvořil odpověď. Odešlete požadavek znovu.

Počítání tokenů

POST /v1/messages/count_tokens přijímá stejné tělo jako požadavek na zprávu (model, system, messages, tools) a vrací {"input_tokens": n}: počet vstupních tokenů, které by se za požadavek účtovaly. Počítá se pro hostované modely s otevřenými váhami, je zdarma a ochrana proti zahlcení jej nezapočítává.

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)

Počítání má vlastní stránku, s endpointem pro prostý text a limity. Počítání tokenů