Overzicht

Endpoints

Elk endpoint staat onder één basis-URL en wordt via HTTPS aangeboden.

https://api.shannon-ai.com

De drie endpoints die tekst produceren, bereiken dezelfde modellen. Kies het endpoint waarvan je code het formaat al gebruikt.

Basis van aanvragen

• De body van elke POST is één JSON-object, tot 32 MiB.
• Een veld dat de API niet kent, veroorzaakt geen fout en heeft geen effect. Een aanvraag die voor een andere provider is geschreven, mislukt niet door een extra veld.
• Een bekend veld met het verkeerde JSON-type, of een ontbrekend verplicht veld, wordt beantwoord met 422. Een body die geen geldige JSON is, wordt beantwoord met 400.
• model is een van de id's op Models & pricing. Hoofdletters en kleine letters maken niet uit.

Een antwoord is JSON, of een stream van server-sent events als de aanvraag stream op true zet. Elk endpoint antwoordt in zijn eigen formaat. Elk antwoord heeft de header x-request-id.

Wat een aanvraag doorloopt

Een aanvraag wordt in een vaste volgorde gecontroleerd voordat een model draait. De eerste controle die mislukt, geeft het antwoord, dus een 401 zegt nog niets over de body.

Foutvorm

Een fout is een JSON-object met een error die type en message bevat. /v1/messages verpakt hem zoals Anthropic-SDK's verwachten; elk ander pad gebruikt de OpenAI-vorm.

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

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

• Lees type en message. code en param zijn alleen bij sommige fouten aanwezig: behandel ze als optioneel. param is altijd null.
• Nadat een stream is begonnen, is de status al 200. Een fout komt dan binnen als een foutframe in de stream.
• Elk foutantwoord bevat de header x-request-id.

Foutafhandeling

Facturering en saldo

• Er is één saldo per account, en chat en API delen het: eerst de planlimiet van vandaag, daarna aangeschaft credit. De API heeft geen eigen quotum.
• Een aanvraag reserveert haar outputbudget (max_tokens, standaard 4,096) en wordt daarna in rekening gebracht voor de tokens die ze echt heeft gebruikt, tegen de prijs van het model.
• Elk antwoord meldt zijn tokenaantallen in usage. De pagina Keys & usage toont het saldo en wat elke aanvraag heeft gekost.
• Elke aanvraag wordt gelijk bediend. De enige limiet op de aanvraagsnelheid is flood protection: 120 aanvragen per minuut per account. Aanvragen die parallel worden verstuurd, wachten in de rij.

Limieten en saldo Modellen en prijzen Sleutels en gebruik

Velden die van het model afhangen

Elk model accepteert dezelfde aanvraag. Enkele velden hebben alleen effect op sommige modellen; de tabel noemt waar. De endpointpagina's vermelden elk veld.

Chat Completions

Als je van een OpenAI-SDK komt

• Stel de basis-URL in op https://api.shannon-ai.com/v1 en de sleutel op je Shannon-sleutel. Aanroepen van Chat Completions en Responses werken dan met de SDK zoals die is.
• model moet een Shannon-id zijn. Een modelnaam van een andere provider, zoals gpt-4o, wordt beantwoord met 400 en unknown model.
• Redenering komt in een eigen veld: reasoning_content naast content, in het bericht en in de streamdelta's.
• Een stream bevat usage altijd in zijn laatste chunk, samen met finish_reason.
• Een toolaanroep in een stream komt binnen als één chunk met de volledige arguments-string.
• Een antwoord heeft één choice.
• Paden van de OpenAI-API die niet in de tabel hierboven staan, zoals /v1/embeddings, worden beantwoord met 404.

Als je van een Anthropic-SDK komt

• Stel de basis-URL in op https://api.shannon-ai.com, zonder /v1, en de sleutel op je Shannon-sleutel. De SDK verstuurt hem als x-api-key.
• model moet een Shannon-id zijn.
• max_tokens is optioneel in deze API. De standaardwaarde is 4,096.
• Een antwoord bevat contentblokken van het type thinking, text en tool_use. Het eerste blok is niet altijd de tekst: kies blokken op type.
• stop_reason is end_turn of tool_use. Een stream van een Shannon-model kan ook eindigen met max_tokens.
• anthropic-version en anthropic-beta worden geaccepteerd, zodat de SDK ongewijzigd werkt. Een aanvraag heeft ze niet nodig.
• Fouten op /v1/messages hebben de Anthropic-vorm: {"type": "error", "error": {…}}.

Codeertools die deze formaten spreken, stel je op dezelfde manier in: basis-URL, sleutel en een Shannon-id als model. CLI-codeertools