Přehled

Endpointy

Každý endpoint leží pod jednou základní URL a obsluhuje se přes HTTPS.

https://api.shannon-ai.com

Tři endpointy, které vytvářejí text, dosáhnou na stejné modely. Zvolte ten, jehož formát už váš kód používá.

Základy požadavků

• Tělo každého POST je jeden objekt JSON, nejvýše 32 MiB.
• Pole, které API nezná, nezpůsobí chybu a nemá žádný účinek. Požadavek psaný pro jiného poskytovatele kvůli nadbytečnému poli neselže.
• Na známé pole se špatným typem JSON nebo na chybějící povinné pole se odpoví 422. Na tělo, které není platný JSON, se odpoví 400.
• model je jedno z id na stránce Modely a ceny. Na velikosti písmen nezáleží.

Odpověď je JSON, nebo stream server-sent events, pokud požadavek nastaví stream na true. Každý endpoint odpovídá ve svém formátu. Každá odpověď má hlavičku x-request-id.

Čím požadavek projde

Požadavek se před spuštěním modelu kontroluje v pevném pořadí. Odpoví první kontrola, která selže, takže 401 o těle zatím nic neříká.

Tvar chyby

Chyba je objekt JSON s polem error, které obsahuje type a message. /v1/messages jej zabalí tak, jak to SDK Anthropic očekávají; každá jiná cesta používá tvar OpenAI.

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

• Čtěte type a message. code a param jsou přítomny jen u některých chyb: považujte je za volitelné. param je vždy null.
• Po zahájení streamu je status už 200. Selhání pak přichází jako chybový rámec uvnitř streamu.
• Každá chybová odpověď nese hlavičku x-request-id.

Zpracování chyb

Fakturace a zůstatek

• Na účet připadá jeden zůstatek, který sdílí chat a API: nejdřív dnešní limit plánu, potom zakoupený kredit. API nemá vlastní kvótu.
• Požadavek si rezervuje svůj výstupní rozpočet (max_tokens, výchozí 4,096) a poté se mu účtují tokeny, které skutečně použil, za cenu modelu.
• Každá odpověď hlásí své počty tokenů v usage. Stránka Klíče a využití ukazuje zůstatek a cenu každého požadavku.
• Každý požadavek se obsluhuje stejně. Jediným limitem frekvence požadavků je ochrana proti zahlcení: 120 požadavků za minutu na účet. Požadavky odeslané paralelně čekají ve frontě.

Limity a zůstatek Modely a ceny Klíče a využití

Pole, která závisí na modelu

Každý model přijímá stejný požadavek. Několik polí se uplatní jen u některých modelů; tabulka říká u kterých. Všechna pole uvádějí stránky endpointů.

Chat Completions

Přicházíte ze SDK OpenAI

• Nastavte základní URL na https://api.shannon-ai.com/v1 a klíč na svůj klíč Shannon. Volání Chat Completions a Responses pak se SDK fungují beze změn.
• model musí být id Shannon. Na název modelu jiného poskytovatele, například gpt-4o, se odpoví 400 a unknown model.
• Uvažování přichází ve vlastním poli: reasoning_content vedle content, ve zprávě i v deltách streamu.
• Stream vždy nese usage ve svém posledním chunku, spolu s finish_reason.
• Volání nástroje ve streamu přichází jako jeden chunk s kompletním řetězcem arguments.
• Odpověď má jednu volbu.
• Na cesty API OpenAI, které nejsou v tabulce výše, například /v1/embeddings, se odpoví 404.

Přicházíte ze SDK Anthropic

• Nastavte základní URL na https://api.shannon-ai.com, bez /v1, a klíč na svůj klíč Shannon. SDK jej posílá jako x-api-key.
• model musí být id Shannon.
• max_tokens je v tomto API volitelné. Výchozí hodnota je 4,096.
• Odpověď obsahuje bloky obsahu typu thinking, text a tool_use. První blok není vždy text: bloky vybírejte podle type.
• stop_reason je end_turn nebo tool_use. Stream modelu Shannon může skončit také s max_tokens.
• anthropic-version a anthropic-beta se přijímají, takže SDK funguje beze změn. Požadavek je nepotřebuje.
• Chyby na /v1/messages mají tvar Anthropic: {"type": "error", "error": {…}}.

Nástroje pro programování, které tyto formáty umějí, se nastavují stejně: základní URL, klíč a id Shannon jako model. CLI nástroje pro programování