> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Realtime WebSocket

> Echtzeit-Sprach- und multimodale Sitzungen per WebSocket verbinden

## Überblick

Dieser Endpunkt ist für Echtzeit-Sitzungen wie Spracherkennung, Sprachsynthese, Sprachübersetzung oder multimodale Realtime-Modelle gedacht. Normale `GET`-Anfragen liefern Metadaten; WebSocket-Upgrades werden an die geroutete Realtime-Upstream-Sitzung weitergeleitet.

## Unterstützte Oberfläche

Dieser Endpunkt ist TokenLabs Realtime-WebSocket-Proxy. Er unterstützt einen normalen `GET /v1/realtime`-Metadatencheck und WebSocket-Upgrades auf demselben Pfad. Er stellt keine OpenAI-Realtime-REST-Hilfsendpunkte bereit, etwa `POST /v1/realtime/client_secrets`, `POST /v1/realtime/translations/client_secrets`, Realtime Calls (`accept`, `hangup`, `refer`, `reject`) oder die Erstellung von legacy beta REST session / transcription-session.

Für Browser- oder Mobile-Apps sollten langfristige API-Keys auf Ihrem Server bleiben. Dieser Endpunkt stellt keine kurzlebigen Realtime client secrets aus.

<Note>Agents sollten zuerst über `/v1/models` ein realtime-fähiges Modell finden und erst danach den Socket öffnen.</Note>

## Verbindung

<ParamField query="model" type="string" required>
  Realtime-Modell-ID. Wählen Sie ein Modell, dessen unterstützte Operationen realtime unterstützt.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer-API-Key. WebSocket-Clients senden beim Upgrade `Authorization: Bearer sk-your-api-key`.
</ParamField>

<RequestExample>
  ```javascript JavaScript theme={null}
  import WebSocket from 'ws';

  const socket = new WebSocket('wss://api.tokenlab.sh/v1/realtime?model=gpt-realtime', {
    headers: { Authorization: 'Bearer sk-your-api-key' }
  });

  socket.on('open', () => {
    socket.send(JSON.stringify({
      type: 'session.update',
      session: { modalities: ['text', 'audio'] }
    }));
  });

  socket.on('message', (data) => {
    console.log('realtime event', data.toString());
  });
  ```

  ```bash cURL theme={null}
  curl "https://api.tokenlab.sh/v1/realtime" \
    -H "Authorization: Bearer sk-your-api-key"
  ```
</RequestExample>

## Nachrichten

TokenLab leitet WebSocket-Nachrichten zwischen Client und geroutetem Realtime-Anbieter weiter. Verwenden Sie die offiziellen Event-Formate des gewählten Modells und geben Sie `model` in der Query an.

## Abrechnung und Schließen

Realtime-Sitzungen nutzen dasselbe API-Key-Guthaben. TokenLab zieht beim Öffnen eine kleine Schätzung vorab ab und rechnet beim Schließen ab oder erstattet.

Schließen Sie den Client-Socket, wenn die Sitzung beendet ist. Schließt der Upstream zuerst, leitet TokenLab den Close-Code nach Möglichkeit weiter.

## Antwortbeispiel

<ResponseExample>
  ```json Connected theme={null}
  {
    "type": "session.created",
    "session": {
      "id": "sess_abc123",
      "model": "gpt-realtime",
      "modalities": ["text", "audio"]
    }
  }
  ```
</ResponseExample>

## Wichtige Felder

<ResponseField name="type" type="string">Von der API zurückgegebener Event- oder Nachrichtentyp.</ResponseField>
<ResponseField name="session.id" type="string">Kennung des Realtime-Anbieters; verwenden Sie sie in Support-Logs, nicht als REST session URL.</ResponseField>