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.
Common rules
| Item | Rule |
|---|---|
| Authentication | Same as HTTP: the Authorization, x-api-key or x-goog-api-key request header |
| Frame size limit | 16 MiB |
| Connection duration | 60 minutes by default (WS_MAX_CONN_DURATION); 120 minutes by default for DashScope Realtime |
| Failure before handshake | Returned as an HTTP status code with plain text; 502 WebSocket upstream failure when the upstream is unavailable |
| Server shutting down | 503 Server is shutting down |
| Pre-forwarding processing | Caller 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(andresponse.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-idandthread-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
/realtimeand/v1/realtimework. The model comes from themodelquery parameter. - Account-level rate limits are checked once when each connection is established.
- Supports
api.openai.comand Alibaba Cloud DashScope (dashscope.aliyuncs.com,dashscope-intl.aliyuncs.com; XSI maps these to/api-ws/v1/realtimeautomatically) 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 returns404if the call is not found and409if the model does not match.
WebRTC calls
POST /v1/realtime/calls- The request body is JSON or multipart, must include
sdpandsession.model, and must not exceed 4 MiB. Only POST is accepted; other methods return405. - Only
api.openai.comupstream keys are used: an empty key pool returns503 No available key, and a selected key that is not OpenAI returns503 No available Realtime provider key. A request body over 4 MiB returns400 Invalid realtime call body. - The
Locationin 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_secretsPassed 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/sessionsThe 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 sendsession.startagain. - 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 HTTP400 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_typeisopenai-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
finishevent was received, so an early disconnect may also be billed. - Use the path with
/v1.