Realtime API

What it does

Real-time streaming speech transcription. Open a WebSocket, send PCM16LE audio frames, receive transcription events.

Endpoint

WSS /v1/audio/transcriptions/stream

Authentication

Three authentication methods:

Method	Usage	Use case
Bearer header	`Authorization: Bearer sk-...`	Server-side clients
Query token	`?access_token=rt_...`	Browser (session token)
Query token (alias)	`?token=rt_...`	Browser (session token)

Session tokens are obtained via POST /v1/audio/transcriptions/session-token and are valid for 60 seconds. See Authentication.

Connection

Upgrade conditions

Request must be a WebSocket upgrade, otherwise 426 websocket_required

Gateway must be enabled, otherwise 503 gateway_disabled

Upstream circuit breaker must be closed, otherwise 503 upstream_unavailable with Retry-After header

Connection quota must pass (concurrent connections + handshake rate)

On success

Receives a session.created event:

{
  "type": "session.created",
  "request_id": "...",
  "session_id": "sess_...",
  "audio": { "format": "pcm_s16le", "sample_rate": 16000, "channels": 1 },
  "turn_detection": { "type": "server_vad" },
  "plan": "free",
  "limits": {
    "max_concurrent_utterances": 2,
    "max_session_seconds": 900,
    "idle_timeout_seconds": 60,
    "remaining_audio_seconds": 3600
  }
}

Message format

All messages are JSON text frames or binary PCM audio frames.

Text frames: JSON objects, must contain a type field

Binary frames: raw PCM audio data (ArrayBuffer)

WebSocket close codes

Code	Close reason	Meaning
1000	—	Normal close
1008	`session_audio_limit`	Realtime session audio budget exceeded
1008	`audio_quota_exhausted`	Billing-window audio budget exhausted
1008	`session_duration_limit`	Session wall-clock duration exceeded
1009	`frame_too_large`	Audio frame exceeds 1 MiB
1011	`client_error`	Client socket error or unexpected gateway error
1013	`upstream_unavailable`	Realtime upstream unavailable (circuit breaker open)
1013	`upstream_backpressure`	Upstream is not draining fast enough
1013	`client_backpressure`	Client is not reading events fast enough
4408	`idle_timeout`	No audio received within idle timeout window

Client Messages — all client-sent messages

Server Events — all server-pushed events

Realtime Quickstart — complete example

Authentication — auth details