Audio & Echtzeit
Realtime WebSocket
Verbinden Sie sich über WebSocket mit Realtime-Voice-Sessions
Übersicht
Verwenden Sie diesen Endpunkt für Realtime-Voice-Sessions. Ein einfacher GET-Request gibt Endpunkt-Metadaten zurück und benötigt keinen API-Key. Ein WebSocket-Upgrade-Request mit ?model={model} öffnet eine Session mit dem ausgewählten Modell.
Nur Modelle, deren Details die Operation realtime auflisten, können eine Session öffnen. Lesen Sie supported_operations in GET /v1/models/{model}, bevor Sie eine Verbindung herstellen. Dieselben Modelldetails listen die Events und Felder auf, die eine Session akzeptiert, wie etwa session.update oder response.create.
Unterstützter Funktionsumfang
GET /v1/realtime ist eine WebSocket-Teilmenge. TokenLab leitet die Realtime-Events des ausgewählten Modells weiter. Es stellt keine OpenAI Realtime REST-Hilfsfunktionen bereit: Session-Erstellung, client_secrets, Calls oder Legacy-Beta-Session-APIs.
Belassen Sie langlebige API-Keys auf Ihrem Server. Dieser Endpunkt stellt keine kurzlebigen Client-Secrets für Browser oder mobile Apps aus.
Realtime-Sessions verwenden die Zustelloption des API-Keys oder Workspaces. Ein X-TokenLab-Delivery-Policy-Header oder Query-String überschreibt diese nicht.
Verbindung
Realtime-Modell-ID. Erforderlich für ein WebSocket-Upgrade.
Bearer sk-your-api-key, gesendet mit dem Upgrade-Request. x-api-key wird ebenfalls akzeptiert. Ein Key im Query-String wird nicht akzeptiert.
Anfrage
import WebSocket from 'ws';
const url = new URL('wss://api.tokenlab.sh/v1/realtime');
url.searchParams.set('model', 'grok-voice-latest');
const socket = new WebSocket(url, {
headers: { Authorization: `Bearer ${process.env.TOKENLAB_API_KEY}` }
});
socket.on('open', () => console.log('Realtime connection open'));
socket.on('message', (data) => {
const event = JSON.parse(data.toString());
if (event.type === 'error') {
console.error('Realtime error', event.status, event.error.code);
return;
}
console.log('realtime event', event.type);
});
socket.on('close', (code, reason) => console.log('closed', code, reason.toString()));Nachrichten
TokenLab leitet WebSocket-Nachrichten zwischen Ihrem Client und dem Modell weiter. Verwenden Sie das Event-Format dieses Modells und übergeben Sie model im Query-String, nicht in jedem Event. Eine Nachricht darf maximal 32 MiB groß sein.
Fehler
Bevor der Socket geöffnet wird, werden Anmeldedaten, die keinen nutzbaren API-Key angeben, mit einem HTTP-Status 401, 403, 429 oder 503 und einem JSON-Fehler-Body abgelehnt.
Nachdem der Socket geöffnet wurde, sendet eine abgelehnte Session eine JSON-Nachricht und schließt anschließend den Socket:
{
"type": "error",
"status": 400,
"error": {
"message": "model query parameter is required",
"type": "invalid_request_error",
"code": "missing_model"
}
}error.code | Ursache |
|---|---|
missing_model | Der Query-Parameter model ist leer |
unsupported_operation | Das Modell ist nicht für die Realtime-API freigegeben |
model_not_allowed, insufficient_balance, quota_exceeded | Der Key kann dieses Modell nicht verwenden, oder das Guthaben bzw. das Key-Limit reicht nicht aus, um die Session-Reservierung zu decken. Siehe API-Fehler behandeln |
Der Dienst schließt den Socket bei diesen Ablehnungen mit dem Code 1008. Weitere Close-Codes: 1009, wenn eine Nachricht zu groß ist, 1013, wenn sich ein Nachrichten-Backlog aufbaut, und 1011, wenn der Dienst die Session nicht weiterleiten oder übertragen kann. Behandeln Sie den Fehler anhand von code, nicht anhand von message.
Abrechnung und Beendigung
Sessions werden über Ihr API-Key-Guthaben abgerechnet. TokenLab reserviert zu Beginn einen geschätzten Betrag, rechnet am Ende die tatsächliche Nutzung ab und erstattet die Differenz. Modelle werden nach Token oder nach Session-Dauer abgerechnet, wie in den jeweiligen Modelldetails angegeben.
Schließen Sie den Client-Socket, wenn die Session beendet ist. Wenn der Dienst die Session zuerst schließt, sendet TokenLab nach Möglichkeit einen Close-Code an Ihren Client.
Antwortbeispiel
Das unten stehende JSON ist die Antwort auf einen gewöhnlichen HTTP-GET-Request. Es handelt sich nicht um ein Session-Event.
Antwort
{
"object": "realtime.endpoint",
"websocket_url": "/v1/realtime?model={model}",
"protocol": "tokenlab_realtime_proxy"
}Wichtige Felder
realtime.endpoint (bei HTTP-GET-Anfragen)./v1/realtime?model={model} (bei HTTP-GET-Anfragen).tokenlab_realtime_proxy (bei HTTP-GET-Anfragen).Autorisierung
BearerAuth API-Key-Authentifizierung. Erstellen oder verwalten Sie API-Keys unter Dashboard > API > API Keys.
Ort: header
Abfrageparameter
Echtzeit-Modell-ID. Erforderlich für WebSocket-Upgrade-Anfragen; optional für einfache HTTP-Metadatenprüfungen.
Antwort
application/json
application/json
application/json
application/json
application/json