Prehľad

Endpointy

Každý endpoint sídli pod jednou základnou URL a obsluhuje sa cez HTTPS.

https://api.shannon-ai.com

Tri endpointy, ktoré tvoria text, dosiahnu tie isté modely. Vyberte ten, ktorého formát váš kód už používa.

Základy requestu

• Telo každého POST je jeden objekt JSON, najviac 32 MiB.
• Pole, ktoré API nepozná, nespôsobí chybu a nemá žiadny účinok. Request napísaný pre iného poskytovateľa nezlyhá kvôli nadbytočnému poľu.
• Na známe pole so zlým typom JSON alebo chýbajúce povinné pole sa odpovie 422. Na telo, ktoré nie je platný JSON, sa odpovie 400.
• model je jedno z id na stránke Modely a ceny. Na veľkých a malých písmenách nezáleží.

Odpoveď je JSON, alebo stream server-sent events, keď request nastaví stream na true. Každý endpoint odpovedá vo vlastnom formáte. Každá odpoveď má hlavičku x-request-id.

Čo request prejde

Request sa pred spustením modelu kontroluje v pevnom poradí. Odpovie prvá kontrola, ktorá zlyhá, takže 401 vám o tele zatiaľ nič nehovorí.

Tvar chyby

Chyba je objekt JSON s error, ktorý obsahuje type a message. /v1/messages ho zabalí tak, ako to očakávajú SDK Anthropic; každá iná cesta používa tvar OpenAI.

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

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

• Čítajte type a message. code a param sú prítomné len pri niektorých chybách: berte ich ako voliteľné. param je vždy null.
• Po začatí streamu je status už 200. Zlyhanie potom príde ako chybový frame vo vnútri streamu.
• Každá chybová odpoveď nesie hlavičku x-request-id.

Spracovanie chýb

Fakturácia a zostatok

• Na účet pripadá jeden zostatok a chat a API ho zdieľajú: najprv dnešný limit plánu, potom zakúpený kredit. API nemá vlastnú kvótu.
• Request si rezervuje svoj výstupný rozpočet (max_tokens, predvolene 4,096) a potom sa mu účtujú tokeny, ktoré skutočne použil, za cenu modelu.
• Každá odpoveď hlási svoje počty tokenov v usage. Stránka Kľúče a využitie ukazuje zostatok a koľko stál každý request.
• Každý request sa obsluhuje rovnako. Jediným limitom frekvencie requestov je ochrana pred zahltením: 120 requestov za minútu na účet. Requesty poslané paralelne čakajú v rade.

Limity a zostatok Modely a ceny Kľúče a využitie

Polia, ktoré závisia od modelu

Každý model berie rovnaký request. Niekoľko polí platí len na niektorých modeloch; tabuľka uvádza kde. Stránky endpointov uvádzajú každé pole.

Chat Completions

Ak prichádzate z SDK OpenAI

• Nastavte základnú URL na https://api.shannon-ai.com/v1 a kľúč na váš kľúč Shannon. Volania Chat Completions a Responses potom s SDK fungujú tak, ako je.
• model musí byť id Shannon. Na názov modelu iného poskytovateľa, napríklad gpt-4o, sa odpovie 400 a unknown model.
• Uvažovanie prichádza vo vlastnom poli: reasoning_content vedľa content, v správe aj v delta streamu.
• Stream vždy nesie usage vo svojom poslednom chunku spolu s finish_reason.
• Volanie nástroja v streame príde ako jeden chunk s úplným reťazcom arguments.
• Odpoveď má jednu voľbu.
• Na cesty API OpenAI, ktoré nie sú v tabuľke vyššie, napríklad /v1/embeddings, sa odpovie 404.

Ak prichádzate z SDK Anthropic

• Nastavte základnú URL na https://api.shannon-ai.com, bez /v1, a kľúč na váš kľúč Shannon. SDK ho posiela ako x-api-key.
• model musí byť id Shannon.
• max_tokens je v tomto API voliteľné. Jeho predvolená hodnota je 4,096.
• Odpoveď obsahuje bloky obsahu typu thinking, text a tool_use. Prvý blok nie je vždy text: bloky vyberajte podľa type.
• stop_reason je end_turn alebo tool_use. Stream modelu Shannon môže skončiť aj s max_tokens.
• anthropic-version a anthropic-beta sa prijímajú, takže SDK funguje bez zmien. Request ich nepotrebuje.
• Chyby na /v1/messages majú tvar Anthropic: {"type": "error", "error": {…}}.

Nástroje na programovanie, ktoré tieto formáty používajú, sa nastavujú rovnako: základná URL, kľúč a id Shannon ako model. CLI nástroje na programovanie