WebSocket 与实时接口
WebSocket 与实时接口
XSI 为长连接与实时语音场景提供专门的适配器。它们与 HTTP 接口共用同一个入口和同一套认证、权限、计费体系。
一个请求同时满足以下条件时按 WebSocket 处理:Connection 含 upgrade、Upgrade: websocket、Sec-WebSocket-Key 非空。
通过反向代理部署时,API 域名必须允许 WebSocket 升级,见《反向代理》。
公共规则
| 项目 | 规则 |
|---|---|
| 认证 | 与 HTTP 相同,使用 Authorization、x-api-key 或 x-goog-api-key 请求头 |
| 单帧上限 | 16 MiB |
| 单连接时长 | 默认 60 分钟(WS_MAX_CONN_DURATION);DashScope Realtime 默认 120 分钟 |
| 握手前失败 | 以 HTTP 状态码加纯文本返回,上游不可用时为 502 WebSocket upstream failure |
| 服务关闭中 | 503 Server is shutting down |
| 转发前处理 | 剥离调用方凭证、Sec-WebSocket-* 等逐跳头;子协议 openai-insecure-api-key.* 与 bearer.* 不会发给上游 |
浏览器无法为 WebSocket 设置自定义请求头,而 XSI 不把 openai-insecure-api-key.* 子协议当作 XSI 凭证。浏览器端实时语音请使用 Realtime WebRTC 或由服务端代理连接。
Responses WebSocket 模式
与 OpenAI Responses WebSocket 模式语义一致:
wss://<API 域名>/v1/responses- 每个
response.create(以及response.steer)都会独立做准入:资源白名单、账号状态与额度、账号级限速、模型白名单与模型限额。 - 准入失败时,XSI 发送一个错误事件后关闭连接:
{"type": "error", "status": 403, "error": {"message": "...", "type": "...", "code": "...", "status": 403, "retryable": false}}模型白名单或模型限额不通过时,此处一律为 403(HTTP 接口中模型限额返回 429)。
- 粘性会话只依据握手请求头
session_id、conversation_id、session-id、thread-id。 - 首次连接上游时最多尝试 3 个 Key(
WS_RESPONSES_INITIAL_CONNECT_ATTEMPTS)。 - 每个 response 按上游返回的用量单独计费。
Codex 的 WebSocket 配置示例见《Codex CLI / App》。
Realtime
WebSocket
wss://<API 域名>/v1/realtime?model=<model>/realtime、/v1/realtime均可。模型来自查询参数model。- 每条连接在建立时做一次账号级限速检查。
- 支持
api.openai.com与阿里云 DashScope(dashscope.aliyuncs.com、dashscope-intl.aliyuncs.com,XSI 自动映射到/api-ws/v1/realtime)上游。 - 附着到已存在的 WebRTC 通话:
?call_id=<XSI 返回的通话 ID>。XSI 会校验通话属于当前账号且模型一致,找不到时返回404,模型不一致时返回409。
WebRTC 通话
POST /v1/realtime/calls- 请求体为 JSON 或 multipart,必须包含
sdp与session.model,大小不超过 4 MiB;只接受 POST,否则返回405。 - 仅使用
api.openai.com上游 Key:Key 池为空时返回503 No available key,选中的 Key 不是 OpenAI 时返回503 No available Realtime provider key。请求体超过 4 MiB 返回400 Invalid realtime call body。 - 响应中的
Location被改写为/v1/realtime/calls/<XSI 通话 ID>,绑定有效期 65 分钟。服务端可用这个 ID 通过 WebSocket?call_id=附着到通话。
临时客户端密钥
POST /v1/realtime/client_secrets透传给上游。用于路由、权限与计费的模型名依次取请求体顶层 model、查询参数 model,都没有时为 gpt-realtime;session.model 不参与判断。
Live 会话
Live 是面向 gpt-live-1 的实时会话接口,按时长计费。WebRTC 会话在上游建会成功后起计 15 秒,之后按累计时长抵扣;主 WebSocket 按上游上报的秒数计费;委托给其他模型的 Token 与工具费用另计。
WebRTC(HTTP)
POST /v1/live/sessions请求体为 JSON,必须包含 session.model(非空,≤ 256 字节)、transport.type = "webrtc" 与 transport.sdp,大小不超过 4 MiB。
WebSocket
wss://<API 域名>/v1/live/sessions
wss://<API 域名>/v1/live/sessions/{id}/attach- 主连接(
/v1/live/sessions)升级后,须在 30 秒内发送首帧{"type": "session.start", "session": {"model": "gpt-live-1"}}(≤ 4 MiB);附着连接(/attach)直接使用已有会话,不能再发送session.start。 - 不接受查询参数,否则返回
400 Live sessions do not accept query parameters; put the model in session.start。 - 映射后的模型必须是
gpt-live-1。WebRTC 建会以 HTTP400 Public Live sessions require gpt-live-1返回;WebSocket 升级后发生的错误以错误事件与关闭帧报告。 - 仅使用 OpenAI 上游 Key,或
config.provider_type为openai-live的兼容上游。 - 账号级限速在
session.start时检查。
DeepSeek 语音合成 WebSocket
wss://<API 域名>/v1/tools/tts- 仅适用于 DeepSeek 上游,消息格式与 DeepSeek 官方一致。
- 认证可以使用请求头,也可以在浏览器中使用子协议:
Sec-WebSocket-Protocol: tts, bearer.<XSI API Key>。该子协议凭证只对这一路由有效。 - 按客户端提交的累计字符数计费(汉字计 2 个字符):会话结束时只要已提交字符且未收到失败的
finish事件即计费,提前断开也可能计费。 - 请使用带
/v1的路径。