TokenLab

Audio & Realtime

Realtime WebSocket

Connect to realtime voice sessions over WebSocket

GET
/v1/realtime

Overview

Use this endpoint for realtime voice sessions. A plain GET request returns endpoint metadata and needs no API key. A WebSocket upgrade request with ?model={model} opens a session with the selected model.

Only models whose details list the realtime operation can open a session. Read supported_operations in GET /v1/models/{model} before you connect. The same model details list the events and fields a session accepts, such as session.update or response.create.

Supported surface

GET /v1/realtime is a WebSocket subset. TokenLab relays the realtime events of the selected model. It does not provide OpenAI Realtime REST helpers: session creation, client_secrets, Calls, or legacy beta session APIs.

Keep long-lived API keys on your server. This endpoint does not issue short-lived client secrets for browsers or mobile apps.

Realtime sessions use the delivery option of the API key or Workspace. A X-TokenLab-Delivery-Policy header or query string does not override it.

Connection

modelstringqueryrequired

Realtime model ID. Required for a WebSocket upgrade.

Authorizationstringheaderrequired

Bearer sk-your-api-key, sent with the upgrade request. x-api-key is accepted as well. A key in the query string is not accepted.

Request

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()));

Messages

TokenLab relays WebSocket messages between your client and the model. Use the event format of that model, and put model in the query string, not in each event. A message can be at most 32 MiB.

Errors

Before the socket opens, a credential that names no usable API key is refused with an HTTP 401, 403, 429, or 503 and a JSON error body.

After the socket opens, a rejected session sends one JSON message and then closes the socket:

{
  "type": "error",
  "status": 400,
  "error": {
    "message": "model query parameter is required",
    "type": "invalid_request_error",
    "code": "missing_model"
  }
}
error.codeCause
missing_modelThe model query parameter is empty
unsupported_operationThe model is not published for the Realtime API
model_not_allowed, insufficient_balance, quota_exceededThe key cannot use this model, or the balance or key limit cannot cover the session reservation. See Handle API errors

The service closes the socket with code 1008 for these rejections. Other close codes: 1009 when a message is too large, 1013 when a message backlog builds up, and 1011 when the service cannot route or relay the session. Handle the error by code, not by message.

Billing and closing

Sessions are billed against your API key balance. TokenLab reserves an estimate at the start, then settles the actual usage at the end and refunds the difference. Models are billed by token or by session time, as their model details show.

Close the client socket when the session is complete. If the service closes the session first, TokenLab sends a close code to your client when possible.

Response example

The JSON below is the response to an ordinary HTTP GET. It is not a session event.

Response

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

Important fields

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

Authorization

BearerAuth
AuthorizationBearer <token>

API Key authentication. Create or manage API keys in Dashboard > API > API Keys.

In: header

Query Parameters

model?string

Realtime model ID. Required for WebSocket upgrade requests; optional for plain HTTP metadata checks.

Response

application/json

application/json

application/json

application/json

application/json