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

ItemRule
AuthenticationSame as HTTP: the Authorization, x-api-key, or x-goog-api-key header
Frame limit16 MiB
Connection duration60 minutes by default; 120 minutes for Alibaba Cloud DashScope Realtime
Failure before handshakeReturned as an HTTP status with plain text; 502 WebSocket upstream failure when the upstream is unavailable
Server shutting down503 Server is shutting down
Risk-guard blockWhile 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 (and response.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.create requests may be queued on one connection, totaling at most 32 MiB; beyond that, a retryable error event is returned with status 429 and error.code websocket_queue_full, and the connection stays usable.
  • Sticky sessions rely only on the handshake headers session_id, conversation_id, session-id, and thread-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 /realtime and /v1/realtime work. The model comes from the model query 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: 404 when not found, 409 on a model mismatch.

WebRTC calls

POST /v1/realtime/calls
  • The body is JSON or multipart and must contain sdp and session.model, at most 4 MiB; only POST is accepted, otherwise 405.
  • 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 is 503 (No available key or No available Realtime provider key).
  • Location in 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_secrets

Passed 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 APICodex Live V3
PlanPlans whose upstream is the official OpenAI APICodex plans
Create a sessionPOST /v1/live/sessions (JSON), or the WebSocket first frame session.startPOST /v1/live (multipart or JSON with sdp and session)
Protocol headerNoneopenai-alpha: quicksilver=v2 (required)
Attach to the sessionwss://api.xairouter.com/v1/live/sessions/{id}/attachwss://api.xairouter.com/v1/live/{call_id}
EventsOfficial OpenAI events such as session.input_transcript.deltaLive 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/sessions

The 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 send session.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 HTTP 400 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 sdp and session) or JSON, with sdp and session.model, at most 4 MiB.
  • Send the header openai-alpha: quicksilver=v2 and do not set type in session. The Router forwards both as they are, so related errors come from the upstream.
  • Success returns HTTP 201 with the answer SDP as the body, and Location is 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 finish event was received; disconnecting early may still be billed.
  • Use the path with /v1.