API-Referenz

SUB&SUB stellt einen Multi-Provider-Relay unter https://api.subnsub.com/v1 bereit. OpenAI-Clients sprechen /v1/chat/completions an; Anthropic-Clients /v1/messages. Derselbe sk-cf-...-Key routet beide — du wählst das Modell im Request-Body und der Relay wählt das Upstream.

Dienstverfügbarkeit

Schnellstart

Für ein bestehendes Konto mit API-Zugriff benötigen Sie drei Dinge:

1. Base-URL: https://api.subnsub.com/v1 (OpenAI-Clients) oder https://api.subnsub.com (Anthropic-Clients — das SDK hängt /v1/messages selbst an)
2. API-Key: sk-cf-..., ausgestellt über die Konsole
3. Modell: eines der 16 unterstützten Modelle – z.B. gpt-5.4-mini oder claude-sonnet-5

Authentifizierung

Jede Anfrage muss einen Authorization: Bearer sk-cf-...-Header tragen. Keys werden über die Konsole ausgestellt und als SHA-256-Hashes gespeichert — sobald du den Erstellungsbildschirm verlässt, ist der Klartext für immer weg, also speichere ihn sofort.

Endpoints

Die stabile öffentliche Oberfläche ist unten und im maschinenlesbaren OpenAPI-3.1-Dokument beschrieben. Nicht aufgeführte Felder können an den Upstream weitergeleitet werden, gehören aber nicht automatisch zur Kompatibilitätszusage von SUB&SUB.

POST /v1/chat/completions

Sende eine Chat-Completion-Anfrage. Die Request-Struktur entspricht der OpenAI Chat Completions API — die OpenAI-SDKs funktionieren unverändert.

POST /v1/responses

OpenAI Responses API – die neuere OpenAI-Anfrageform (client.responses.create(...)). Funktioniert mit jedem Katalogmodell: gpt-* nativ, claude-* über dieselbe Kompatibilitätsbrücke wie Chat/Completions. Die Nutzung wird identisch gemessen – Eingabe-/Ausgabe-Tokens zum Tarif des Modells.

Ausführbares Responses-Beispiel:

curl https://api.subnsub.com/v1/responses \
  -H "Authorization: Bearer sk-cf-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": "Explain exponential backoff in two sentences."
  }'

POST /v1/messages

Anthropic-nativer Endpoint für die claude-*-Modelle — das Anthropic-SDK (anthropic-sdk-python, @anthropic-ai/sdk, claude-code) funktioniert unverändert gegen diesen Pfad. Richte deine Base-URL auf https://api.subnsub.com und authentifiziere dich über den x-api-key-Header (die Authorization-Bearer-Form funktioniert ebenfalls, falls dein Client sie bevorzugt).

Ausführbares Anthropic-Messages-Beispiel:

curl https://api.subnsub.com/v1/messages \
  -H "x-api-key: sk-cf-xxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

POST /v1/messages/count_tokens

Zählen Sie die Token eines Anthropic-formatierten Prompts vor dem Senden. Verwenden Sie dieselben Felder x-api-key, anthropic-version, model, system, messages und tools wie bei /v1/messages. Dieser Endpunkt wird nicht berechnet. Ein Suffix :online wird entfernt; Suchergebnisse werden weder abgerufen noch mitgezählt.

curl https://api.subnsub.com/v1/messages/count_tokens \
  -H "x-api-key: sk-cf-xxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Count this prompt."}]
  }'

GET /v1/models

Listen Sie die Modelle auf, die Sie tatsächlich verwenden können. Das Relay überprüft den Zustand beider Upstream-Familien und gibt die 16 verifizierten öffentlichen IDs zurück – dieselbe Whitelist, die auch die POST-Endpunkte erzwingen, sodass Discovery niemals ein Modell ankündigt, das 400 wäre. Wenn der Upstream-Katalog nicht erreichbar ist, gibt der Endpunkt 502 models_unreachable anstelle einer irreführenden leeren Liste zurück.

# sample response (truncated)
{
  "object": "list",
  "data": [
    { "id": "gpt-5.4-mini",      "type": "model", ... },
    { "id": "gpt-5.4",           "type": "model", ... },
    { "id": "claude-sonnet-5",     "type": "model", ... },
    { "id": "claude-fable-5",      "type": "model", ... },
    ...
  ]
}

Kompatibilitätszusage

OpenAI-kompatibel bedeutet nicht, dass jedes Feld jedes Upstream-Modells auf jeder Route garantiert ist. Es gelten drei Supportstufen:

Verfügbare Modelle

Zwei vorgelagerte Familien. Die 7 OpenAI-Modelle leiten an gemeinsam genutzte ChatGPT-Konten weiter; Die 9 Claude-Modelle werden von offiziellen Anthropic-Konten bedient. Die Preise pro Token hängen von der Stufe ab (siehe Preise) – der gleiche Schlüssel funktioniert für beide.

OpenAI

Anthropic

Reasoning-Aufwand

Jedes oben genannte OpenAI-Modell ist ein Argumentationsmodell – das Backend kann mehr oder weniger „Denk“-Tokens ausgeben, bevor es sichtbare Ausgaben ausgibt. Legen Sie reasoning_effort für den Anforderungstext OpenAI /v1/chat/completions (oder reasoning: {"effort": ...} für /v1/responses) fest, um das Budget zu kontrollieren. Verwenden Sie für Claude die Anthropic-nativen Felder thinking und output_config.effort – siehe Abschnitt /v1/messages. Die OpenAI-Modelle akzeptieren die gleichen fünf Aufwandswerte:

# Two equivalent forms — pick whichever your SDK supports
{
  "model": "gpt-5.4-mini",
  "reasoning_effort": "high",
  "messages": [ ... ]
}

{
  "model": "gpt-5.5",
  "reasoning": { "effort": "xhigh" },
  "messages": [ ... ]
}

Streaming

Setze "stream": true, um Server-Sent Events zu empfangen. Der letzte Chunk trägt einen usage-Block (wir erzwingen stream_options.include_usage upstream, sodass Token-Zählungen immer ausgegeben werden), danach schließt ein wörtliches data: [DONE] den Stream.

# Streaming format (line by line)
data: {"id":"resp_...","choices":[{"delta":{"content":"Hi"}}]}

data: {"id":"resp_...","choices":[{"delta":{"content":"!"}}]}

data: {"id":"resp_...","choices":[],"usage":{"prompt_tokens":18,"completion_tokens":11,"total_tokens":29}}

data: [DONE]

Ausführbares Python-Streaming-Beispiel:

from openai import OpenAI

client = OpenAI(
    api_key="sk-cf-xxxxxxxxxxxx",
    base_url="https://api.subnsub.com/v1",
)

stream = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)
for chunk in stream:
    text = chunk.choices[0].delta.content if chunk.choices else None
    if text:
        print(text, end="", flush=True)

Websuche

Hänge :online an eine beliebige vom Endpoint unterstützte Modell-ID an, und der Relay führt vor dem Weiterleiten an das Modell eine Websuche durch und stellt die Ergebnisse der Konversation voran, damit die Antwort auf frischen Daten basiert. Der Suffix funktioniert auf /v1/chat/completions und /v1/messages (Letzteres erfordert weiterhin eine claude-*-Basis); es sind keine suchspezifischen Request-Felder erforderlich.

# Same call as before — just :online on the model
curl https://api.subnsub.com/v1/chat/completions \
  -H "Authorization: Bearer sk-cf-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini:online",
    "messages": [
      {"role": "user", "content": "What did Anthropic ship this week?"}
    ]
  }'

So funktioniert es: Der Relay entfernt :online, nimmt die jüngste User-Nachricht als Query (auf 400 Zeichen begrenzt), ruft Tavily für bis zu 3 Ergebnisse mit extrahiertem Seitentext (falls verfügbar) auf, plus eine optionale von Tavily generierte Zusammenfassung, und stellt sie dann demselben User-Turn als klar abgegrenzten <search_results>-Block voran, bevor die Anfrage upstream gesendet wird. Der Suchaufruf hat einen Timeout von 8 Sekunden. Die Ergebnisse werden bewusst in die User-Rolle eingefügt — niemals in den System-Prompt — sodass nicht vertrauenswürdige Snippets nicht auf System-Priorität angehoben werden können.

Der <search_results>-Block sieht so aus. Ihm geht eine einzeilige Anweisung voraus, die das Modell anweist, den Block als nicht vertrauenswürdige externe Daten zu behandeln und nummerierte Einträge inline zu zitieren:

<search_results query="What did Anthropic ship this week?" retrieved="2026-05-21">
Summary: <short LLM-generated synthesis of the result set>

[1] Anthropic launches Opus 4.8
URL: https://www.anthropic.com/news/opus-4-8
<extracted page text, or short snippet if extraction failed — up to ~2000 chars>

[2] ...
</search_results>

Wann :online verwenden

Der Relay macht einen einzigen Tavily-Aufruf pro Anfrage und fügt die Ergebnisse ein — es ist keine agentische Suchschleife. Das Modell entscheidet nicht anhand des Gesehenen, erneut zu suchen, wie es Perplexity Sonar oder das Browse-Tool von ChatGPT tun. Plane diese Einschränkung ein:

Formuliere die letzte User-Nachricht als eigenständige Suchanfrage. Die Suche läuft gegen den wörtlichen Text deines jüngsten User-Turns (auf 400 Zeichen begrenzt), sodass konversationelle Rückfragen wie "und was ist mit der neuesten Version?" zu nutzlosen Queries ohne Kontext werden. Wiederhole in einem Mehrturn-Chat das Thema, wenn du :online hinzufügst — z. B. "neueste Version des Anthropic Python SDK" statt "die neueste".

Für Fragen, die mehrstufige Synthese brauchen (Vergleichen-und-Gegenüberstellen, tiefe Recherche), zerlege sie in mehrere Turns und füge jedem :online hinzu. Das Modell liest die frischen Ergebnisse jedes Turns; du steuerst die nächste Query manuell. Beachte, dass der eingefügte <search_results>-Block nur upstream gesendet wird — er wird nicht an deinen Client zurückgespiegelt und nicht in die nächste Anfrage übernommen. Wenn also ein späterer Turn von Details früherer Quellen abhängt, bitte das Modell, sie in seiner sichtbaren Antwort zusammenzufassen. Ein One-Shot-Recherchemodus wird nicht unterstützt.

Fehler

Der Umschlag hängt davon ab, welchen Endpoint du aufgerufen hast — der Relay gibt Fehler im Protokoll zurück, das zum SDK des Aufrufers passt, und Upstream-Fehler werden wörtlich durchgereicht.

OpenAI-Pfade (/v1/chat/completions, /v1/responses, /v1/models) — OpenAI-Umschlag:

{ "error": { "message": "...", "type": "...", "code": "..." } }

Anthropic-Pfade (/v1/messages, /v1/messages/count_tokens) — Anthropic-Umschlag:

{ "type": "error", "error": { "type": "...", "message": "..." } }

Der Anthropic-Umschlag verwendet eine andere Struktur — kein code-Feld, und der Diskriminator type: "error" steht auf oberster Ebene (wobei das innere error.type die Kategorie angibt, z. B. authentication_error, invalid_request_error, permission_error, api_error). Anthropic-SDKs parsen diese Struktur bereits; gewöhnliche OpenAI-SDK-Fehlerhandler tun das nicht, rufe /v1/messages also mit einem Anthropic-SDK auf (oder nutze rohes HTTP).

Die Statuscodes sind über beide Protokolle hinweg die kanonischen HTTP-Codes:

Wiederholungen & Zuverlässigkeit

Verwenden Sie begrenzte Wiederholungen. Das Relay nutzt gemeinsame Upstream-Kapazität, und Generierungsanfragen sind nicht idempotent.

• Wiederholen: 429, 502, 503 und eindeutig vorübergehende 500-Antworten. Beachten Sie retry-after; andernfalls nutzen Sie exponentiellen Backoff mit Jitter (z. B. 1 s, 2 s, 4 s; höchstens drei Versuche).
• Nicht unverändert wiederholen: 400, 401, 402 oder 403. Korrigieren Sie zuerst Payload, Schlüssel, Guthaben oder Zugriffsstatus.
• Duplikatrisiko: Jeder erfolgreiche Generierungsversuch ist eine eigene kostenpflichtige Anfrage. SUB&SUB dedupliziert Generierungs-POSTs derzeit nicht über einen Idempotenzschlüssel. Verwenden Sie daher eine Vorgangs-ID in Ihrer Anwendung und wiederholen Sie nicht nach einer vollständigen Antwort.
• Streaming: Ein unterbrochener SSE-Stream kann nicht fortgesetzt werden. Eine neue Verbindung startet eine neue Generierung und kann erneut berechnet werden.

Preise & Abrechnung

Pay-as-you-go, abgerechnet pro Token in Mikrodollar (1 Mikro = $0,000001 = 1/10.000 Cent), sodass Anfragen unter einem Cent genau erfasst werden. Die Sätze gelten pro 1M Tokens, nach Tier — siehe die Modelltabelle, welchem Tier jedes Modell zugeordnet ist.

Die Preise für Fable und Ultra entsprechen den veröffentlichten Listenpreisen von Anthropic. Sonnet 5 nutzt bis zum 31. August 2026 den Einführungspreis von 2 $/10 $ von Anthropic; Der nach diesem Datum veröffentlichte Standardpreis beträgt 3 $/15 $. Die anderen Stufen liegen dank der gebündelten Abonnementunterstützung unter den Upstream-Tarifen.

Reasoning-Tokens (wenn Sie reasoning_effort auf OpenAI oder das native thinking-Feld von Anthropic auf Claude festlegen) zählen als Output-Tokens zum Stufensatz des Modells – es gibt keinen gesonderten Aufpreis für hohen Aufwand, aber eine Deep-Thinking-Anfrage kann leicht 10–50-mal mehr Output erzeugen Tokens als eins ohne Aufwand, so dass der Dollarschein mit ihm skaliert.

Anthropic-Prompt-Caching wird als separater Posten abgerechnet: Cache-Writes mit 1,25× und Cache-Reads mit 0,10× des Eingabe-Satzes des Tiers. Ein haiku-4.5-Cache-Hit kostet also 0.20 × 0.10 = $0.02 per 1M tokens, und ein sonnet-4.5-Cache-Hit kostet 0.75 × 0.10 = $0.075 per 1M tokens. Cache-Tokens werden pro Anfrage einzeln in der Abrechnung erfasst — die Konsole zeigt die Aufschlüsselung.

Das Guthaben wird in Echtzeit abgezogen, sobald jede Anfrage zurückkehrt — bei Streaming-Anfragen läuft die Abrechnung, nachdem der [DONE]-Chunk eingetroffen ist. Sieh dir dein Live-Guthaben und die Abrechnungen pro Anfrage unter /console#billing an.

Rate-Limits

Heute keine Rate-Limits pro Key. Gemeinsame Upstream-Kapazität und anbieterseitiges Throttling gelten weiterhin; wenn du an diese stößt, gibt der Relay 429 mit einem retry-after-Header zurück. Limits für RPM / TPM pro Key sind geplant.

Status & Support

• Angemeldete Konten mit API-Zugriff sehen den Live-Status der Provider unter Konsole → Dienststatus und Betriebsmeldungen unter Systemhinweis.
• Hilfe zu Konto, Abrechnung, Datenschutz oder Sicherheit erhalten Sie per E-Mail an [email protected].
• Geben Sie bei einem API-Fehler UTC-Zeitstempel, Endpunkt, Modell, HTTP-Status und das sichtbare Präfix des API-Schlüssels an. Senden Sie niemals den vollständigen Schlüssel oder Prompt-Inhalt, außer der Support bittet ausdrücklich um eine geschwärzte Reproduktion.
• Der Dienst wird nach bestem Bemühen und ohne SLA betrieben. Verfügbarkeit und Erstattungen regeln die nur englisch verfügbaren Nutzungsbedingungen; die Datenschutzerklärung beschreibt die Datenverarbeitung.

Dokumentation zuletzt geprüft: 14. Juli 2026.