Überblick

Endpunkte

Jeder Endpunkt liegt unter einer Base-URL und wird über HTTPS bedient.

https://api.shannon-ai.com

Die drei Endpunkte, die Text erzeugen, erreichen dieselben Modelle. Wählen Sie den, dessen Format Ihr Code bereits verwendet.

Grundlagen zu Anfragen

• Der Body jedes POST ist ein JSON-Objekt, bis zu 32 MiB.
• Ein Feld, das die API nicht kennt, verursacht keinen Fehler und hat keine Wirkung. Eine für einen anderen Anbieter geschriebene Anfrage scheitert nicht an einem zusätzlichen Feld.
• Ein bekanntes Feld mit dem falschen JSON-Typ oder ein fehlendes Pflichtfeld wird mit 422 beantwortet. Ein Body, der kein gültiges JSON ist, wird mit 400 beantwortet.
• model ist eine der IDs unter Modelle & Preise. Groß- und Kleinschreibung spielen keine Rolle.

Eine Antwort ist JSON oder ein Stream aus Server-Sent Events, wenn die Anfrage stream auf true setzt. Jeder Endpunkt antwortet in seinem eigenen Format. Jede Antwort hat den Header x-request-id.

Was eine Anfrage durchläuft

Eine Anfrage wird in fester Reihenfolge geprüft, bevor ein Modell läuft. Die erste Prüfung, die fehlschlägt, antwortet, sodass ein 401 noch nichts über den Body aussagt.

Form eines Fehlers

Ein Fehler ist ein JSON-Objekt mit einem error, das type und message enthält. /v1/messages verpackt es so, wie es die Anthropic-SDKs erwarten; jeder andere Pfad verwendet die OpenAI-Form.

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

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

• Lesen Sie type und message. code und param sind nur bei manchen Fehlern vorhanden: Behandeln Sie sie als optional. param ist immer null.
• Nachdem ein Stream begonnen hat, ist der Status bereits 200. Ein Fehler trifft dann als Fehler-Frame innerhalb des Streams ein.
• Jede Fehlerantwort enthält den Header x-request-id.

Fehlerbehandlung

Abrechnung und Guthaben

• Es gibt ein Guthaben pro Konto, und Chat und API teilen es: zuerst das heutige Plan-Kontingent, dann gekauftes Guthaben. Die API hat kein eigenes Kontingent.
• Eine Anfrage reserviert ihr Output-Budget (max_tokens, Standard 4,096) und wird dann für die Tokens berechnet, die sie tatsächlich verbraucht hat, zum Preis des Modells.
• Jede Antwort meldet ihre Token-Anzahlen in usage. Die Seite Keys & Nutzung zeigt das Guthaben und was jede Anfrage gekostet hat.
• Jede Anfrage wird gleich bedient. Das einzige Limit für die Anfragerate ist der Flood-Schutz: 120 Anfragen pro Minute und Konto. Parallel gesendete Anfragen warten in der Schlange.

Limits und Guthaben Modelle & Preise Keys & Nutzung

Felder, die vom Modell abhängen

Jedes Modell nimmt dieselbe Anfrage an. Einige Felder wirken nur bei manchen Modellen; die Tabelle nennt, wo. Die Seiten der Endpunkte listen jedes Feld auf.

Chat Completions

Wenn Sie von einem OpenAI-SDK kommen

• Setzen Sie die Base-URL auf https://api.shannon-ai.com/v1 und den Key auf Ihren Shannon-Key. Aufrufe von Chat Completions und Responses funktionieren dann mit dem SDK, so wie es ist.
• model muss eine Shannon-ID sein. Ein Modellname eines anderen Anbieters, etwa gpt-4o, wird mit 400 und unknown model beantwortet.
• Reasoning kommt in einem eigenen Feld: reasoning_content neben content, in der Nachricht und in den Stream-Deltas.
• Ein Stream trägt usage immer in seinem letzten Chunk, zusammen mit finish_reason.
• Ein Tool-Aufruf in einem Stream trifft als ein Chunk mit dem vollständigen arguments-String ein.
• Eine Antwort hat eine Choice.
• Pfade der OpenAI API, die nicht in der Tabelle oben stehen, etwa /v1/embeddings, werden mit 404 beantwortet.

Wenn Sie von einem Anthropic-SDK kommen

• Setzen Sie die Base-URL auf https://api.shannon-ai.com, ohne /v1, und den Key auf Ihren Shannon-Key. Das SDK sendet ihn als x-api-key.
• model muss eine Shannon-ID sein.
• max_tokens ist bei dieser API optional. Der Standard ist 4,096.
• Eine Antwort enthält Content-Blöcke vom Typ thinking, text und tool_use. Der erste Block ist nicht immer der Text: Wählen Sie Blöcke nach type.
• stop_reason ist end_turn oder tool_use. Ein Stream eines Shannon-Modells kann auch mit max_tokens enden.
• anthropic-version und anthropic-beta werden akzeptiert, sodass das SDK unverändert funktioniert. Eine Anfrage braucht sie nicht.
• Fehler bei /v1/messages haben die Anthropic-Form: {"type": "error", "error": {…}}.

Coding-Tools, die diese Formate sprechen, werden genauso eingerichtet: Base-URL, Key und eine Shannon-ID als Modell. CLI-Coding-Tools