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 建会以 HTTP 400 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 的路径。

相关文档