WebSocket and Realtime APIs

WebSocket and Realtime APIs

XSI provides dedicated adapters for long-lived connections and realtime voice. They share the same endpoint and the same authentication, permission and billing system as the HTTP APIs.

A request is handled as a WebSocket when all of the following hold: Connection contains upgrade, Upgrade: websocket is set, and Sec-WebSocket-Key is non-empty.

When deployed behind a reverse proxy, the API domain must allow WebSocket upgrades. See Reverse Proxy.

Common rules

ItemRule
AuthenticationSame as HTTP: the Authorization, x-api-key or x-goog-api-key request header
Frame size limit16 MiB
Connection duration60 minutes by default (WS_MAX_CONN_DURATION); 120 minutes by default for DashScope Realtime
Failure before handshakeReturned as an HTTP status code with plain text; 502 WebSocket upstream failure when the upstream is unavailable
Server shutting down503 Server is shutting down
Pre-forwarding processingCaller credentials and hop-by-hop headers such as Sec-WebSocket-* are stripped; the openai-insecure-api-key.* and bearer.* subprotocols are never sent upstream

Browsers cannot set custom headers on WebSockets, and XSI does not treat the openai-insecure-api-key.* subprotocol as an XSI credential. For realtime voice in the browser, use Realtime WebRTC or proxy the connection through your server.

Responses WebSocket mode

Semantics match OpenAI's Responses WebSocket mode:

wss://<API domain>/v1/responses
  • Each response.create (and response.steer) goes through admission independently: resource allowlist, account status and credit, account-level rate limits, model allowlist and model-level limits.
  • If admission fails, XSI sends one error event and then closes the connection:
{"type": "error", "status": 403, "error": {"message": "...", "type": "...", "code": "...", "status": 403, "retryable": false}}

Failures of the model allowlist or model-level limits are always 403 here (on the HTTP APIs, model-level limits return 429).

  • Sticky sessions are based only on the handshake request headers session_id, conversation_id, session-id and thread-id.
  • On the initial upstream connection, XSI tries at most 3 keys (WS_RESPONSES_INITIAL_CONNECT_ATTEMPTS).
  • Each response is billed separately based on the usage returned by the upstream.

For a Codex WebSocket configuration example, see Codex CLI / App.

Realtime

WebSocket

wss://<API domain>/v1/realtime?model=<model>
  • Both /realtime and /v1/realtime work. The model comes from the model query parameter.
  • Account-level rate limits are checked once when each connection is established.
  • Supports api.openai.com and Alibaba Cloud DashScope (dashscope.aliyuncs.com, dashscope-intl.aliyuncs.com; XSI maps these to /api-ws/v1/realtime automatically) upstreams.
  • To attach to an existing WebRTC call: ?call_id=<call ID returned by XSI>. XSI verifies that the call belongs to the current account and that the model matches; it returns 404 if the call is not found and 409 if the model does not match.

WebRTC calls

POST /v1/realtime/calls
  • The request body is JSON or multipart, must include sdp and session.model, and must not exceed 4 MiB. Only POST is accepted; other methods return 405.
  • Only api.openai.com upstream keys are used: an empty key pool returns 503 No available key, and a selected key that is not OpenAI returns 503 No available Realtime provider key. A request body over 4 MiB returns 400 Invalid realtime call body.
  • The Location in the response is rewritten to /v1/realtime/calls/<XSI call ID>, and the binding is valid for 65 minutes. Your 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 in the request body, then the model query parameter, and defaults to gpt-realtime if neither is present; session.model is not considered.

Live sessions

Live is the realtime session API for gpt-live-1, billed by duration. A WebRTC session is charged 15 seconds once the upstream session is created successfully, and that amount is then offset against the accumulated duration; the main WebSocket is billed by the seconds reported upstream; tokens and tool fees for work delegated to other models are billed separately.

WebRTC (HTTP)

POST /v1/live/sessions

The request body is JSON, must include session.model (non-empty, ≀ 256 bytes), transport.type = "webrtc", and transport.sdp, and must not exceed 4 MiB.

WebSocket

wss://<API domain>/v1/live/sessions
wss://<API domain>/v1/live/sessions/{id}/attach
  • After the main connection (/v1/live/sessions) is upgraded, the first frame {"type": "session.start", "session": {"model": "gpt-live-1"}} (≀ 4 MiB) must be sent within 30 seconds; an attach connection (/attach) uses the existing session directly and cannot send session.start again.
  • Query parameters are not accepted; otherwise XSI returns 400 Live sessions do not accept query parameters; put the model in session.start.
  • The mapped model must be gpt-live-1. WebRTC session creation returns HTTP 400 Public Live sessions require gpt-live-1; errors after a WebSocket upgrade are reported as error events and close frames.
  • Only OpenAI upstream keys, or compatible upstreams whose config.provider_type is openai-live, are used.
  • Account-level rate limits are checked at session.start.

DeepSeek text-to-speech WebSocket

wss://<API domain>/v1/tools/tts
  • Applies only to DeepSeek upstreams; the message format matches DeepSeek's official API.
  • Authenticate with a request header, or in the browser with a subprotocol: Sec-WebSocket-Protocol: tts, bearer.<XSI API Key>. This subprotocol credential is valid only for this route.
  • Billing is by the cumulative number of characters submitted by the client (each 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, so an early disconnect may also be billed.
  • Use the path with /v1.