Preskočiť na obsah
Formát Anthropic

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)

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.

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

Na hostovaných open-weight modeloch usage hlási tokeny prečítané z prompt cache oddelene od ostatných vstupných tokenov.

200 JSON
{
  "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:

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á:

200 content
[
  {
    "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:

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)

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.

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

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

400 JSON
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}
Stav Typ Správa Kedy
401 authentication_error Missing authentication
Invalid 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)

Počítanie má vlastnú stránku s endpointom pre čistý text a s limitmi. Počítanie tokenov