> ## 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

> Connect to realtime speech and multimodal sessions over WebSocket

## Overview

Use this endpoint for realtime sessions such as streaming speech recognition, speech synthesis, speech translation, or realtime multimodal models. Non-WebSocket `GET` requests return endpoint metadata; WebSocket upgrade requests proxy the realtime upstream session.

## Supported surface

This endpoint is TokenLab's realtime WebSocket proxy. It supports a plain `GET /v1/realtime` metadata check and WebSocket upgrades on the same path. It does not expose OpenAI Realtime REST helper endpoints such as `POST /v1/realtime/client_secrets`, `POST /v1/realtime/translations/client_secrets`, Realtime Calls (`accept`, `hangup`, `refer`, `reject`), or legacy beta REST session / transcription-session creation.

For browser or mobile apps, keep long-lived API keys on your server. This endpoint does not issue short-lived Realtime client secrets.

<Note>For agents, discover realtime-capable models with `/v1/models` and choose a model whose supported endpoints include realtime before opening the socket.</Note>

## Connection

<ParamField query="model" type="string" required>
  Realtime model ID. Use a model whose model details lists realtime support.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer API key. WebSocket clients should send `Authorization: Bearer sk-your-api-key` during the upgrade request.
</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>

## Messages

TokenLab forwards WebSocket messages between your client and the routed realtime provider. Keep provider-specific event shapes for the selected realtime model, and include `model` in the query string rather than in each event.

## Billing and closing

Realtime sessions use the same API key balance as other endpoints. TokenLab pre-deducts a small estimate when the socket opens, then settles or refunds when the session closes.

Close the client socket when the session is complete. If the upstream closes first, TokenLab relays that close code to your client when possible.

## Response example

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

## Important fields

<ResponseField name="type" type="string">Event or message type returned by the API.</ResponseField>
<ResponseField name="session.id" type="string">Identifier emitted by the realtime provider; include it in support logs, not as a REST session URL.</ResponseField>