TokenLab-HTTP-Header und native Protokoll-Endpunkte verstehen

Protokoll-Endpunkte bestimmen Payload-Schemas

TokenLab verwendet keine dynamischen Formathinweis-Header (wie z. B. proprietäre Format-Hint-Tags), um Antwortschemas zur Laufzeit anzuzeigen. Stattdessen werden Payload-Strukturen strikt durch den aufgerufenen Endpunkt bestimmt. Das Parsen von Client-Antworten erfordert das Weiterleiten von Anfragen an den nativen Zielprotokoll-Endpunkt, anstatt Response-Header auf Payload-Typen hin zu untersuchen:

• Chat Completions (/v1/chat/completions): Verwendet OpenAI-kompatible Schemas, die choices, message.content und einen usage-Block (prompt_tokens, completion_tokens, total_tokens) zurückgeben.
• Responses (/v1/responses): Folgt dem OpenAI Responses API-Format für Hintergrundaufgaben, Server-Tools und Response-Events.
• Anthropic Messages (/v1/messages): Interagiert mit Anthropic Claude-Modellen unter Verwendung des nativen Anthropic-Schemas (content-Blöcke, thinking und output_tokens). Wenn Sie das Anthropic SDK konfigurieren, setzen Sie die Basis-URL auf https://api.tokenlab.sh ohne das /v1-Präfix.
• Gemini (/v1beta/models/:model:generateContent): Akzeptiert native Gemini-Schemas (contents, Parts) und gibt standardmäßige Gemini-REST-Kandidatenobjekte zurück.

Bevor Sie eine Modell-Anfrage weiterleiten, prüfen Sie anhand von Get a Model (GET /v1/models/{model}) oder durch Einsehen des Modellkatalogs, welche Protokolle das Modell akzeptiert. Überprüfen Sie das Array tokenlab.accepted_request_formats in der Antwort. Umfassende Regeln zur Endpunktzuordnung finden Sie im Leitfaden zu API-Formaten.

Dokumentierte Request-Header

Alle Standardaufrufe an TokenLab-Endpunkte erfordern bestimmte HTTP-Request-Header:

• Authorization: Übergibt Anmeldedaten als Bearer-Token (Authorization: Bearer $TOKENLAB_API_KEY). Management-Endpunkte erfordern ein Management-Token (Authorization: Bearer mt-...).
• Content-Type: Muss bei POST-Anfragen mit JSON-Body application/json sein.

Dokumentierte Response-Header

TokenLab gibt Standard- und benutzerdefinierte HTTP-Header für Rate-Limits, Abrechnungsabgleich und die Verwaltung asynchroner Aufgaben zurück:

Rate-Limiting-Header

Wenn eine Anfrage die Grenzwerte der Kontoebene überschreitet, gibt TokenLab den Status HTTP 429 rate_limit_exceeded zusammen mit zwei Headern zurück:

• Retry-After: Gibt die erforderliche Wartezeit in Sekunden an, bevor der Aufruf wiederholt werden kann.
• X-RateLimit-Limit: Gibt Ihr aktives Limit an Anfragen pro Minute (Requests per Minute) für die authentifizierte Ebene an.

Verwenden Sie für Wiederholungsversuche immer den Wert des Retry-After-Headers, anstatt feste Backoff-Zeiten fest im Code zu hinterlegen. Weitere Einzelheiten zur Fehlerbehebung finden Sie im Leitfaden zu Rate-Limits.

Abrechnungs- und Observability-Header

Für nicht-streamende und asynchrone Interaktionen stellt TokenLab Identifikations-Header bereit, um Kosten und Hintergrundprozesse nachzuverfolgen:

• X-Billing-Transaction-ID: Wird zurückgegeben, wenn die Abrechnung abgeschlossen ist, bevor die HTTP-Antwort gesendet wird. Nicht-streamende, OpenAI-kompatible Endpunkte enthalten billing_transaction_id im JSON-Body, Gemini- und native Format-Endpunkte geben diese Information jedoch über diesen Header aus. Streaming-Aufrufe werden möglicherweise erst nach dem Schließen der Verbindung abgerechnet; falls der Header fehlt, rufen Sie die ID aus den Nutzungsdaten des Workspace ab. Einzelheiten zu Abrechnungsabläufen finden Sie im Leitfaden zu Abrechnung und Preisen.
• X-Task-ID: Wird in Response-Headern zurückgegeben, wenn asynchrone Aufträge für Video-, Musik-, 3D- oder aufgabenbasierte Bildgenerierung erstellt werden. Er liefert eine Korrelations-ID auf Header-Ebene, die der id der Aufgabe entspricht. Konsultieren Sie den Leitfaden zu Logs und Fehlerbehebung für Logging-Standards.

Implementierung: Header erfassen und bei 429 wiederholen

Das folgende Python-Beispiel veranschaulicht, wie Sie eine Anfrage an den Chat-Completions-Endpunkt senden, Transaktions-IDs auslesen und Retry-After-Header bei Erreichen von Rate-Limits verarbeiten:

import os
import time
import requests

API_KEY = os.environ["TOKENLAB_API_KEY"]
ENDPOINT = "https://api.tokenlab.sh/v1/chat/completions"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "Summarize system status."}]
}

max_attempts = 3
for attempt in range(max_attempts):
    response = requests.post(ENDPOINT, headers=headers, json=payload, timeout=30)

    if response.status_code == 200:
        # Check for billing transaction header on settled non-streaming calls
        billing_id = response.headers.get("X-Billing-Transaction-ID")
        data = response.json()
        print(f"Settled Transaction ID: {billing_id}")
        print(data["choices"][0]["message"]["content"])
        break

    elif response.status_code == 429:
        retry_after = response.headers.get("Retry-After")
        limit = response.headers.get("X-RateLimit-Limit")
        wait_seconds = float(retry_after) if retry_after else 2 ** attempt
        print(f"Rate limit reached ({limit} req/min). Retrying in {wait_seconds}s...")
        time.sleep(wait_seconds)
    else:
        response.raise_for_status()

Best Practices für Logging und Observability

Protokollieren Sie bei der Implementierung von Request-Monitoring die in Headern und Payloads zurückgegebenen öffentlichen Tracking-IDs, um Einträge abzugleichen, ohne Benutzer-Prompts oder Zugangsdaten dauerhaft zu speichern:

• Halten Sie request_id, X-Billing-Transaction-ID und X-Task-ID zusammen mit Status-Codes und Antwortlatenzen fest.
• Entfernen Sie Authorization-Header, unverschlüsselte API-Keys und private signierte URLs stets aus Telemetrie-Pipelines.
• Fragen Sie für den serverseitigen Finanzabgleich GET /v1/management/api-keys/{keyId}/usage ab, anstatt Dashboard-Seiten auszulesen (Scraping) oder Summen allein anhand von reinen Token-Zählern zu schätzen.