Realtime WebSocket

OverviewCopy Anchor Link

Use this endpoint for realtime sessions such as streaming speech recognition, speech synthesis, speech translation, or realtime multimodal models. A standard GET request returns endpoint metadata, while a WebSocket upgrade request opens a realtime session for the selected model.

Supported surfaceCopy Anchor Link

TokenLab exposes a realtime WebSocket endpoint at GET /v1/realtime for metadata checks and WebSocket upgrades. Treat it as a WebSocket subset: it forwards supported realtime model events, and it does not support OpenAI Realtime REST helper surfaces such as session creation, client_secrets, Calls call-control APIs, or legacy beta session APIs.

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

ConnectionCopy Anchor Link

import WebSocket from 'ws';

const model = process.env.TOKENLAB_REALTIME_MODEL;
const apiKey = process.env.TOKENLAB_API_KEY;
if (!model || !apiKey) {
  throw new Error('Set TOKENLAB_REALTIME_MODEL and TOKENLAB_API_KEY');
}

const url = new URL('wss://api.tokenlab.sh/v1/realtime');
url.searchParams.set('model', model);
const socket = new WebSocket(url, {
  headers: { Authorization: `Bearer ${apiKey}` }
});

socket.on('open', () => {
  console.log('Realtime connection open');
});

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

socket.on('error', (error) => console.error(error.message));
socket.on('close', (code) => console.log('Realtime connection closed', code));

MessagesCopy Anchor Link

TokenLab relays WebSocket messages between your client and the selected realtime model. Use the event format documented for that model, and include model in the query string rather than in each event.

Billing and closingCopy Anchor Link

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 any difference.

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

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

Important fieldsCopy Anchor Link