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));
curl "https://api.tokenlab.sh/v1/realtime" \
-H "Authorization: Bearer sk-your-api-key"
{
"object": "realtime.endpoint",
"websocket_url": "/v1/realtime?model={model}",
"protocol": "tokenlab_realtime_proxy"
}
Audio & Realtime
Realtime WebSocket
Connect to realtime speech and multimodal sessions over WebSocket
GET
/
v1
/
realtime
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));
curl "https://api.tokenlab.sh/v1/realtime" \
-H "Authorization: Bearer sk-your-api-key"
{
"object": "realtime.endpoint",
"websocket_url": "/v1/realtime?model={model}",
"protocol": "tokenlab_realtime_proxy"
}
Overview
Use this endpoint for realtime sessions such as streaming speech recognition, speech synthesis, speech translation, or realtime multimodal models. A standardGET request returns endpoint metadata, while a WebSocket upgrade request opens a realtime session for the selected model.
Supported surface
TokenLab exposes a realtime WebSocket endpoint atGET /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.
Choose a current realtime model from
/v1/models and verify /v1/models/{model} before setting TOKENLAB_REALTIME_MODEL. Session events and configuration depend on that model. The JSON response example below is for an ordinary HTTP GET, not a WebSocket session event.Connection
string
required
Realtime model ID. Use a model whose model details lists realtime support.
string
required
Bearer API key. WebSocket clients should send
Authorization: Bearer sk-your-api-key during the upgrade request.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));
curl "https://api.tokenlab.sh/v1/realtime" \
-H "Authorization: Bearer sk-your-api-key"
Messages
TokenLab relays WebSocket messages between your client and the selected realtime model. Use the event format documented for that model, and includemodel in the query string rather than in each event.
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 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.Response example
{
"object": "realtime.endpoint",
"websocket_url": "/v1/realtime?model={model}",
"protocol": "tokenlab_realtime_proxy"
}
Important fields
string
realtime.endpoint (HTTP GET).string
/v1/realtime?model={model} (HTTP GET).string
tokenlab_realtime_proxy (HTTP GET).string
Event or message type returned by the API.
string
Realtime session ID for logs and support.
Authorizations
API Key authentication. Create or manage API keys in Dashboard > API > API Keys.
Query Parameters
Realtime model ID to route the WebSocket session. Required for WebSocket upgrade requests; optional for plain HTTP metadata checks.
Response
WebSocket connection established