Kern

API-Referenz

Endpoints, Authentifizierung, Antwort-Header und Fehler

Übersicht

TokenLab unterstützt OpenAI-kompatible Endpoints sowie die Anfrageformate von Anthropic und Gemini. Bestehende OpenAI-Clients können /v1 verwenden; wählen Sie ein anderes Format nur dann, wenn Ihre Anwendung ein spezifisches Verhalten benötigt, das für diese API erforderlich ist. POST /v1/responses ist optional und hängt von der Modellunterstützung ab.

Basis-URL

https://api.tokenlab.sh

Authentifizierung

Modellanfragen verwenden einen TokenLab API-Key. Der Standard-Authentifizierungs-Header lautet:

Authorization: Bearer sk-your-api-key

GET /v1/models, GET /v1/models/{model}, GET /v1/models/{model}/pricing und GET /v1/pricing sind öffentlich und benötigen keinen Key. Anthropic Messages akzeptiert auch x-api-key; Gemini akzeptiert x-goog-api-key oder ?key= sowie Bearer-Authentifizierung. /v1/management/* erfordert ein Management-Token (mt-...).

Sie erhalten Ihren API-Key über die Console.

Bereitstellungsrichtlinie (Delivery Policy)

Generierungsanfragen akzeptieren X-TokenLab-Delivery-Policy: auto | verified | official. Ein Request-Header überschreibt die Einstellung des API-Keys, welche wiederum den Workspace-Standard überschreibt.

  • Auto verwendet TokenLab Verified, falls verfügbar, andernfalls Official. Sie bezahlen für die Option, die Ihre Anfrage abschließt.
  • TokenLab Verified ist eine von TokenLab verifizierte Bereitstellung. Es gilt der Verified-Preis.
  • Official berechnet den Official-Preis, welcher dem vom Modellhersteller veröffentlichten Preis entspricht.
  • Echtzeit-Sitzungen (Realtime sessions) verwenden den API-Key oder die Workspace-Einstellung und akzeptieren keine Request-Überschreibung.

Ein ungültiger Header gibt 400 zurück. Wenn die angeforderte Option nicht verfügbar ist, gibt TokenLab 503 delivery_tier_unavailable sowie eine Request-ID zurück. Lesen Sie retryable: Wenn für den ausgewählten Vorgang kein Angebot verfügbar ist, ist dieser Wert false. Wiederholen Sie dieselbe Anfrage nicht unverändert.

API-Seiten mit einem Anfrageformular akzeptieren Ihren TokenLab API-Key und senden echte Anfragen. Diese Anfragen belasten Ihr Kontoguthaben und Ihre Limits. Sie können auch cURL, Postman oder ein SDK verwenden.

Unterstützte Endpoints

Chat & Textgenerierung

EndpointMethodeBeschreibung
/v1/chat/completionsPOSTOpenAI-kompatible Chat-Completions
/v1/messagesPOSTAnthropic-kompatible Messages
/v1/messages/count_tokensPOSTEingabe-Tokens einer Messages-Anfrage zählen
/v1/messages/batchesPOST, GETMessage-Batches erstellen und auflisten
/v1/messages/batches/{message_batch_id}GET, DELETEMessage-Batch abrufen oder löschen
/v1/messages/batches/{message_batch_id}/resultsGETErgebnisse lesen
/v1/messages/batches/{message_batch_id}/cancelPOSTMessage-Batch abbrechen
/v1/responsesPOSTOpenAI Responses API
/v1/responses/{id}GET, DELETEGespeicherte Antwort abrufen oder löschen
/v1/responses/compactPOSTKontext einer Responses-Konversation komprimieren
/v1/translationsPOSTText-zu-Text-Übersetzung

Embeddings & Rerank

EndpointMethodeBeschreibung
/v1/embeddingsPOSTText-Embeddings erstellen
/v1/multimodal/embeddingsPOSTEmbeddings mit einem multimodalen Embedding-Modell erstellen
/v1/rerankPOSTDokumente neu bewerten (Rerank)

Entscheidungen

EndpointMethodeBeschreibung
/v1/systemonePOSTTypisierte Entscheidungsfragen auswerten

Dateien & Batches

EndpointMethodeBeschreibung
/v1/filesPOST, GETDateien hochladen und auflisten
/v1/files/{file_id}GET, DELETEDatei abrufen oder löschen
/v1/files/{file_id}/contentGETDateiinhalt herunterladen
/v1/batchesPOST, GETBatches erstellen und auflisten
/v1/batches/{batch_id}GETBatch abrufen
/v1/batches/{batch_id}/cancelPOSTBatch abbrechen

Bilder

EndpointMethodeBeschreibung
/v1/images/generationsPOSTBilder aus Text generieren
/v1/images/editsPOSTBilder bearbeiten
/v1/images/variationsPOSTBildvariationen erstellen
/v1/images/generations/{id}GETKompatibilitäts-Statuspfad für aufgabenbasierte Bildantworten

Modelle für Bilder können ein fertiges Bild oder eine asynchrone Aufgabe zurückgeben. Wenn die Antwort status: "pending" oder eine Aufgaben-ID enthält, fragen Sie GET /v1/tasks/{id} ab.

Audio

EndpointMethodeBeschreibung
/v1/audio/speechPOSTText-zu-Sprache (TTS)
/v1/audio/transcriptionsPOSTSprache-zu-Text (STT)
/v1/audio/translationsPOSTSprache in englischen Text übersetzen

Echtzeit (Realtime)

EndpointMethodeBeschreibung
/v1/realtime?model={model}WSEchtzeit-WebSocket-Sitzungen

Verwenden Sie /v1/realtime für WebSocket-Upgrades. Ein einfaches GET /v1/realtime gibt Endpoint-Metadaten zurück. Dies ist nicht die OpenAI Realtime REST-Oberfläche; client-secret, Calls und Legacy-Beta-Sitzungs-Endpoints sind nicht verfügbar.

Video

EndpointMethodeBeschreibung
/v1/videos/generationsPOSTVideo-Generierungsaufgabe erstellen
/v1/videos/generations/{id}GETKompatibilitäts-Statuspfad
/v1/videos/assetsPOST, GETSeedance-Material-Assets erstellen und auflisten
/api/v3/contents/generations/tasksPOST, GETSeedance-Aufgaben mit dem Volcengine-Anfrageformat

Fragen Sie GET /v1/tasks/{id} mit der Aufgaben-id ab. /v1/videos/generations/{id} bleibt für bestehende Integrationen verfügbar.

Asynchrone Aufgaben

EndpointMethodeBeschreibung
/v1/tasks/{id}GETStatus für jede asynchrone Aufgabe
/v1/tasks/{id}DELETEAsynchrone Aufgabe abbrechen

Fragen Sie GET /v1/tasks/{id} für jede asynchrone Aufgabe ab: Bilder, Video, Musik, 3D, Worlds und asynchrone Audiotranskription. Verwenden Sie die id oder task_id aus der Erstellungsantwort. Eine Worlds-Erstellungsantwort gibt eine poll_url unter /v1/worlds/generations/{id} zurück; fragen Sie dort ebenfalls /v1/tasks/{id} ab. Die modalitätsspezifischen Statuspfade auf dieser Seite sind Kompatibilitäts-Endpoints für bestehende Integrationen.

Musik

EndpointMethodeBeschreibung
/v1/music/generationsPOSTMusik-Generierungsaufgabe erstellen
/v1/music/generations/{id}GETKompatibilitäts-Statuspfad

3D-Generierung

EndpointMethodeBeschreibung
/v1/3d/generationsPOST3D-Modell-Generierungsaufgabe erstellen
/v1/3d/generations/{id}GETKompatibilitäts-Statuspfad

Worlds

EndpointMethodeBeschreibung
/v1/worlds/generationsPOSTWorld-Generierungsaufgabe erstellen
/v1/worlds/listPOSTWorlds auflisten
/v1/worlds/{id}GET, DELETEWorld abrufen oder löschen
/v1/worlds/media-assets/prepare-uploadPOSTMedien-Asset-Upload vorbereiten

Modelle & Preise

EndpointMethodeBeschreibung
/v1/modelsGETAlle verfügbaren Modelle auflisten
/v1/models/{model}GETSpezifische Modellinformationen abrufen
/v1/models/{model}/pricingGETPreise eines Modells abrufen
/v1/pricingGETModellpreise auflisten

Gemini (v1beta)

Native Unterstützung des Google Gemini API-Formats:

EndpointMethodeBeschreibung
/v1beta/modelsGETModelle auflisten, die Gemini-Anfragen akzeptieren
/v1beta/models/{model}GETModell abrufen
/v1beta/models/{model}:generateContentPOSTInhalt generieren
/v1beta/models/{model}:streamGenerateContentPOSTInhalt streamen
/v1beta/models/{model}:countTokensPOSTTokens zählen
/v1beta/files, /v1beta/cachedContentsPOST, GET, DELETEGemini-Dateien und zwischengespeicherte Inhalte

Gemini-Endpoints unterstützen zusätzlich zur Standard-Bearer-Token-Authentifizierung den Abfrageparameter ?key=.

Management

/v1/management/* verwaltet Guthaben, API-Keys und Webhooks mit einem Management-Token. Siehe Management-API.

Antwortformat

Jeder Endpoint behält sein API-Format bei. Die Erfolgs- und Fehlerbeispiele unten verwenden das Chat-Completions-Format.

Erfolgsantwort

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-5.6-terra",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello!"}, "finish_reason": "stop"}],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

Antwort-Header

Verwenden Sie diese Header, wenn sie vorhanden sind.

HeaderBeschreibung
X-Request-IDAnfrage-Identifikator für Support und Debugging
X-Routing-Time-MSNicht-Streaming: Gesamtzeit in Millisekunden bis zur Antwort des Upstreams, einschließlich Warteschlange und Inferenz beim Upstream. Streaming: immer 0. Keine Messung von Routing oder Warteschlange.
X-Task-IDÖffentlicher asynchroner Aufgaben-Identifikator für aufgabenbasierte Antworten
X-Billing-Transaction-IDAbrechnungs-Transaktions-Identifikator nach der endgültigen Abrechnung

Offizielle Ablehnungen von Anfragen können upstream mit dem vom Dienst gemeldeten Fehler und dem öffentlichen Dienstnamen enthalten. Siehe API-Fehler behandeln.

Fehlerantwort

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_api_key",
    "code": "invalid_api_key"
  }
}

Ratenbegrenzungen (Rate Limits)

Die Limits hängen vom Kontotyp ab und gelten pro API-Key. Eine 429-Antwort enthält Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Siehe Ratenbegrenzungen für die Stufen und wie man Wiederholungsversuche durchführt.

OpenAPI-Spezifikation

OpenAPI Spec

Laden Sie die vollständige OpenAPI 3.1-Spezifikation herunter

Auf dieser Seite