WebSocket and Realtime APIs
WebSocket and Realtime APIs
Long-lived connections and realtime voice share the same endpoint as the HTTP APIs, and the same authentication, permission, and billing system.
A request is handled as a WebSocket when all of the following hold: Connection contains upgrade, Upgrade: websocket, and Sec-WebSocket-Key is non-empty.
Common rules
| Item | Rule |
|---|---|
| Authentication | Same as HTTP: the Authorization, x-api-key, or x-goog-api-key header |
| Frame limit | 16 MiB |
| Connection duration | 60 minutes by default; 120 minutes for Alibaba Cloud DashScope Realtime |
| Failure before handshake | Returned as an HTTP status with plain text; 502 WebSocket upstream failure when the upstream is unavailable |
| Server shutting down | 503 Server is shutting down |
| Risk-guard block | While an account is temporarily blocked, the handshake or later requests are rejected with 403, see Errors |
Browsers cannot set custom headers on a WebSocket, and the openai-insecure-api-key.* subprotocol is not accepted as a credential. For browser-side realtime voice, use Realtime WebRTC or proxy the connection from your server.
Responses WebSocket mode
Semantics match OpenAI's Responses WebSocket mode:
wss://api.xairouter.com/v1/responses- Every
response.create(andresponse.steer) is admitted independently: resource allowlist, account status and credit, account-level rate limits, model allowlist, and model limits. - When admission fails, the Router sends one error event and then closes the connection:
{"type": "error", "status": 403, "error": {"message": "...", "type": "...", "code": "...", "status": 403, "retryable": false}}A model allowlist or model limit rejection is always 403 here (the HTTP APIs return 429 for model limits).
- By default, at most 8
response.createrequests may be queued on one connection, totaling at most 32 MiB; beyond that, a retryable error event is returned withstatus429anderror.codewebsocket_queue_full, and the connection stays usable. - Sticky sessions rely only on the handshake headers
session_id,conversation_id,session-id, andthread-id. - The first upstream connection tries at most 3 upstreams.
- Each response is billed separately by the usage the upstream reports.
For a Codex WebSocket configuration example, see Codex CLI / App.
Realtime
WebSocket
wss://api.xairouter.com/v1/realtime?model=<model>- Both
/realtimeand/v1/realtimework. The model comes from themodelquery parameter. - Each connection goes through one account-level rate-limit check when it is established.
- Realtime models from OpenAI and Alibaba Cloud DashScope are supported.
- To attach to an existing WebRTC call, use
?call_id=<call ID returned when the call was created>. The Router verifies that the call belongs to the current account and the model matches:404when not found,409on a model mismatch.
WebRTC calls
POST /v1/realtime/calls- The body is JSON or multipart and must contain
sdpandsession.model, at most 4 MiB; only POST is accepted, otherwise405. - A body over 4 MiB or in the wrong format returns
400 Invalid realtime call body. When the account's group has no available realtime voice upstream, the response is503(No available keyorNo available Realtime provider key). Locationin the response is rewritten to/v1/realtime/calls/<call ID>, bound for 65 minutes. A server can use this ID to attach to the call over WebSocket with?call_id=.
Ephemeral client secrets
POST /v1/realtime/client_secretsPassed through to the upstream. The model name used for routing, permissions, and billing is taken from the top-level model of the body, then the model query parameter, and is gpt-realtime when neither exists; session.model is not considered.
Live sessions
Live is the realtime voice session API for gpt-live-1. The Router offers two Live integrations, each tied to a different upstream line:
| OpenAI Live API | Codex Live V3 | |
|---|---|---|
| Plan | Plans whose upstream is the official OpenAI API | Codex plans |
| Create a session | POST /v1/live/sessions (JSON), or the WebSocket first frame session.start | POST /v1/live (multipart or JSON with sdp and session) |
| Protocol header | None | openai-alpha: quicksilver=v2 (required) |
| Attach to the session | wss://api.xairouter.com/v1/live/sessions/{id}/attach | wss://api.xairouter.com/v1/live/{call_id} |
| Events | Official OpenAI events such as session.input_transcript.delta | Live V3 events such as output_transcript.added and turn.done |
Which one you use depends on the upstream line of your plan; the request bodies and events of the two cannot be mixed. See the blog post Two Ways to Call gpt-live-1 for full examples and an error reference.
OpenAI Live API
Billed by duration. A WebRTC session counts 15 seconds from successful creation and is then deducted by accumulated duration; the primary WebSocket is billed by the seconds the upstream reports; tokens and tool fees of delegated models are billed separately.
WebRTC (HTTP)
POST /v1/live/sessionsThe body is JSON and must contain session.model (non-empty, at most 256 bytes), transport.type = "webrtc", and transport.sdp, at most 4 MiB.
WebSocket
wss://api.xairouter.com/v1/live/sessions
wss://api.xairouter.com/v1/live/sessions/{id}/attach- After the primary connection is upgraded, send the first frame
{"type": "session.start", "session": {"model": "gpt-live-1"}}within 30 seconds (at most 4 MiB); an attach connection (/attach) uses an existing session and must not sendsession.start. - Query parameters are not accepted:
400 Live sessions do not accept query parameters; put the model in session.start. - The mapped model must be
gpt-live-1. WebRTC creation returns HTTP400 Public Live sessions require gpt-live-1; errors after a WebSocket upgrade are reported as an error event plus a close frame. - Account-level rate limits are checked at
session.start. - When the upstream of your plan is not the official OpenAI API, the response is
503 No OpenAI Live project key at the configured model level; use Codex Live V3 instead.
Codex Live V3
POST /v1/live
wss://api.xairouter.com/v1/live/{call_id}- The body follows the rules of WebRTC calls: multipart (fields
sdpandsession) or JSON, withsdpandsession.model, at most 4 MiB. - Send the header
openai-alpha: quicksilver=v2and do not settypeinsession. The Router forwards both as they are, so related errors come from the upstream. - Success returns HTTP
201with the answer SDP as the body, andLocationis rewritten to/v1/live/<call ID>. The sideband connects to/v1/live/{call_id}with the same key and protocol header. - When the upstream of your plan is not the Codex line, the upstream returns
Your account does not have access to Quicksilver v2 sessions.; use the OpenAI Live API instead.
DeepSeek speech synthesis WebSocket
wss://api.xairouter.com/v1/tools/tts- Available for DeepSeek models only; the message format matches the official DeepSeek one.
- Authenticate with headers, or in a browser with the subprotocol
Sec-WebSocket-Protocol: tts, bearer.<API Key>. The subprotocol credential works for this route only. - Billed by the cumulative number of characters the client submits (a Chinese character counts as 2): when the session ends, it is billed as long as characters were submitted and no failed
finishevent was received; disconnecting early may still be billed. - Use the path with
/v1.