[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"article-doc:docs\u002Fapi-reference\u002Frealtime-api":3},"---\ntitle: Realtime API\ndescription: WebSocket endpoint for streaming transcription.\n---\n## What it does\n\nReal-time streaming speech transcription. Open a WebSocket, send PCM16LE audio frames, receive transcription events.\n\n## Endpoint\n\n```\nWSS \u002Fv1\u002Faudio\u002Ftranscriptions\u002Fstream\n```\n\n## Authentication\n\nThree authentication methods:\n\n| Method | Usage | Use case |\n|---|---|---|\n| Bearer header | `Authorization: Bearer sk-...` | Server-side clients |\n| Query token | `?access_token=rt_...` | Browser (session token) |\n| Query token (alias) | `?token=rt_...` | Browser (session token) |\n\nSession tokens are obtained via `POST \u002Fv1\u002Faudio\u002Ftranscriptions\u002Fsession-token` and are valid for 60 seconds. See [Authentication](\u002Fdocs\u002Fstart\u002Fauthentication).\n\n## Connection\n\n### Upgrade conditions\n\n- Request must be a WebSocket upgrade, otherwise `426 websocket_required`\n- Gateway must be enabled, otherwise `503 gateway_disabled`\n- Upstream circuit breaker must be closed, otherwise `503 upstream_unavailable` with `Retry-After` header\n- Connection quota must pass (concurrent connections + handshake rate)\n\n### On success\n\nReceives a `session.created` event:\n\n```json\n{\n  \"type\": \"session.created\",\n  \"request_id\": \"...\",\n  \"session_id\": \"sess_...\",\n  \"audio\": { \"format\": \"pcm_s16le\", \"sample_rate\": 16000, \"channels\": 1 },\n  \"turn_detection\": { \"type\": \"server_vad\" },\n  \"plan\": \"free\",\n  \"limits\": {\n    \"max_concurrent_utterances\": 2,\n    \"max_session_seconds\": 900,\n    \"idle_timeout_seconds\": 60,\n    \"remaining_audio_seconds\": 3600\n  }\n}\n```\n\n## Message format\n\nAll messages are JSON text frames or binary PCM audio frames.\n\n- **Text frames**: JSON objects, must contain a `type` field\n- **Binary frames**: raw PCM audio data (ArrayBuffer)\n\n## WebSocket close codes\n\n| Code | Close reason | Meaning |\n|---:|---|---|\n| 1000 | — | Normal close |\n| 1008 | `session_audio_limit` | Realtime session audio budget exceeded |\n| 1008 | `audio_quota_exhausted` | Billing-window audio budget exhausted |\n| 1008 | `session_duration_limit` | Session wall-clock duration exceeded |\n| 1009 | `frame_too_large` | Audio frame exceeds 1 MiB |\n| 1011 | `client_error` | Client socket error or unexpected gateway error |\n| 1013 | `upstream_unavailable` | Realtime upstream unavailable (circuit breaker open) |\n| 1013 | `upstream_backpressure` | Upstream is not draining fast enough |\n| 1013 | `client_backpressure` | Client is not reading events fast enough |\n| 4408 | `idle_timeout` | No audio received within idle timeout window |\n\n## Related\n\n- [Client Messages](\u002Fdocs\u002Fapi-reference\u002Fclient-messages) — all client-sent messages\n- [Server Events](\u002Fdocs\u002Fapi-reference\u002Fserver-events) — all server-pushed events\n- [Realtime Quickstart](\u002Fdocs\u002Frealtime\u002Fquickstart) — complete example\n- [Authentication](\u002Fdocs\u002Fstart\u002Fauthentication) — auth details\n",1790059118947]