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](/docs/start/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 |

Related

[Client Messages](/docs/api-reference/client-messages) — all client-sent messages

[Server Events](/docs/api-reference/server-events) — all server-pushed events

[Realtime Quickstart](/docs/realtime/quickstart) — complete example

[Authentication](/docs/start/authentication) — auth details