Realtime WebSocket

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

curl "https://api.tokenlab.sh/v1/realtime" \
  -H "Authorization: Bearer sk-your-api-key"

{
  "type": "session.created",
  "session": {
    "id": "sess_abc123",
    "model": "gpt-realtime",
    "modalities": ["text", "audio"]
  }
}

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.

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

Connection

model

string

required

Realtime model ID. Use a model whose model details lists realtime support.

Authorization

string

required

Bearer API key. WebSocket clients should send Authorization: Bearer sk-your-api-key during the upgrade request.

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

curl "https://api.tokenlab.sh/v1/realtime" \
  -H "Authorization: Bearer sk-your-api-key"

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

{
  "type": "session.created",
  "session": {
    "id": "sess_abc123",
    "model": "gpt-realtime",
    "modalities": ["text", "audio"]
  }
}

Important fields

type

string

Event or message type returned by the API.

session.id

string

Identifier emitted by the realtime provider; include it in support logs, not as a REST session URL.

Create Translation Create Music

Core

Text

Files & Batches

Images

Audio & Realtime

Music

Video & Materials

Worlds

3D

Async Jobs

Gemini Native

Management

Realtime WebSocket

Overview

Supported surface

Connection

Messages

Billing and closing

Response example

Important fields

​Overview

​Supported surface

​Connection

​Messages

​Billing and closing

​Response example

​Important fields

Overview

Supported surface

Connection

Messages

Billing and closing

Response example

Important fields