Audio & Echtzeit

Realtime WebSocket

Verbinden Sie sich über WebSocket mit Realtime-Voice-Sessions

GET
/v1/realtime

Ü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

modelstringqueryerforderlich

Realtime-Modell-ID. Erforderlich für ein WebSocket-Upgrade.

Authorizationstringheadererforderlich

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.codeUrsache
missing_modelDer Query-Parameter model ist leer
unsupported_operationDas Modell ist nicht für die Realtime-API freigegeben
model_not_allowed, insufficient_balance, quota_exceededDer 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

HTTP GET
{
  "object": "realtime.endpoint",
  "websocket_url": "/v1/realtime?model={model}",
  "protocol": "tokenlab_realtime_proxy"
}

Wichtige Felder

objectstring
realtime.endpoint (bei HTTP-GET-Anfragen).
websocket_urlstring
/v1/realtime?model={model} (bei HTTP-GET-Anfragen).
protocolstring
tokenlab_realtime_proxy (bei HTTP-GET-Anfragen).

Autorisierung

BearerAuth
AuthorizationBearer <token>

API-Key-Authentifizierung. Erstellen oder verwalten Sie API-Keys unter Dashboard > API > API Keys.

Ort: header

Abfrageparameter

model?string

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