Prezentare generală

Endpoint-uri

Fiecare endpoint se află sub un singur base URL și este servit prin HTTPS.

https://api.shannon-ai.com

Cele trei endpoint-uri care produc text ajung la aceleași modele. Alege-l pe cel al cărui format îl folosește deja codul tău.

Noțiuni de bază despre cereri

• Corpul fiecărui POST este un singur obiect JSON, de până la 32 MiB.
• Un câmp pe care API-ul nu îl cunoaște nu provoacă eroare și nu are efect. O cerere scrisă pentru alt furnizor nu eșuează din cauza unui câmp în plus.
• Un câmp cunoscut cu tip JSON greșit sau un câmp obligatoriu lipsă primește răspuns 422. Un corp care nu este JSON valid primește răspuns 400.
• model este unul dintre id-urile din Models & pricing. Majusculele și minusculele nu contează.

Un răspuns este JSON sau un stream de evenimente trimise de server (server-sent events) când cererea setează stream la true. Fiecare endpoint răspunde în formatul său. Fiecare răspuns are header-ul x-request-id.

Ce verificări trece o cerere

O cerere este verificată într-o ordine fixă înainte de rularea unui model. Prima verificare care eșuează dă răspunsul, deci un 401 nu îți spune încă nimic despre corp.

Forma erorilor

O eroare este un obiect JSON cu un error care conține type și message. /v1/messages îl împachetează cum se așteaptă SDK-urile Anthropic; orice altă cale folosește forma OpenAI.

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

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

• Citește type și message. code și param sunt prezente doar la unele erori: tratează-le ca opționale. param este întotdeauna null.
• După ce un stream a început, statusul este deja 200. Un eșec sosește atunci ca un frame de eroare în interiorul stream-ului.
• Fiecare răspuns de eroare conține header-ul x-request-id.

Gestionare erori

Facturare și sold

• Există un singur sold per cont, iar chatul și API-ul îl folosesc împreună: mai întâi cota planului de astăzi, apoi creditul achiziționat. API-ul nu are o cotă proprie.
• O cerere își rezervă bugetul de ieșire (max_tokens, implicit 4,096) și este apoi taxată pentru token-urile folosite efectiv, la prețul modelului.
• Fiecare răspuns raportează numărul de token-uri în usage. Pagina Keys & usage arată soldul și cât a costat fiecare cerere.
• Fiecare cerere este servită egal. Singura limită a ratei cererilor este protecția anti-flood: 120 de cereri pe minut per cont. Cererile trimise în paralel așteaptă la coadă.

Limite și sold Modele și prețuri Chei și utilizare

Câmpuri care depind de model

Fiecare model primește aceeași cerere. Câteva câmpuri au efect doar pe unele modele; tabelul spune care. Paginile endpoint-urilor listează fiecare câmp.

Chat Completions

Dacă vii de la un SDK OpenAI

• Setează base URL la https://api.shannon-ai.com/v1, iar cheia la cheia ta Shannon. Apelurile Chat Completions și Responses funcționează apoi cu SDK-ul așa cum este.
• model trebuie să fie un id Shannon. Un nume de model de la alt furnizor, precum gpt-4o, primește răspuns 400 și unknown model.
• Raționamentul vine într-un câmp propriu: reasoning_content lângă content, în mesaj și în delta-urile stream-ului.
• Un stream conține întotdeauna usage în ultimul chunk, împreună cu finish_reason.
• Un apel de instrument într-un stream sosește ca un singur chunk, cu șirul arguments complet.
• Un răspuns are o singură alegere.
• Căile API-ului OpenAI care nu sunt în tabelul de mai sus, precum /v1/embeddings, primesc răspuns 404.

Dacă vii de la un SDK Anthropic

• Setează base URL la https://api.shannon-ai.com, fără /v1, iar cheia la cheia ta Shannon. SDK-ul o trimite ca x-api-key.
• model trebuie să fie un id Shannon.
• max_tokens este opțional în acest API. Valoarea sa implicită este 4,096.
• Un răspuns conține blocuri de conținut de tip thinking, text și tool_use. Primul bloc nu este întotdeauna textul: alege blocurile după type.
• stop_reason este end_turn sau tool_use. Un stream de la un model Shannon se poate termina și cu max_tokens.
• anthropic-version și anthropic-beta sunt acceptate, deci SDK-ul funcționează neschimbat. O cerere nu are nevoie de ele.
• Erorile de pe /v1/messages au forma Anthropic: {"type": "error", "error": {…}}.

Instrumentele de programare care vorbesc aceste formate se configurează la fel: base URL, cheie și un id Shannon ca model. Instrumente CLI pentru programare