Audio & Realtime
Realtime WebSocket
Connect to realtime voice sessions over WebSocket
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
Realtime model ID. Required for a WebSocket upgrade.
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.code | Cause |
|---|---|
missing_model | The model query parameter is empty |
unsupported_operation | The model is not published for the Realtime API |
model_not_allowed, insufficient_balance, quota_exceeded | The 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
{
"object": "realtime.endpoint",
"websocket_url": "/v1/realtime?model={model}",
"protocol": "tokenlab_realtime_proxy"
}Important fields
realtime.endpoint (HTTP GET)./v1/realtime?model={model} (HTTP GET).tokenlab_realtime_proxy (HTTP GET).Authorization
BearerAuth API Key authentication. Create or manage API keys in Dashboard > API > API Keys.
In: header
Query Parameters
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