WebSocket 与实时接口
WebSocket 与实时接口
长连接与实时语音场景与 HTTP 接口共用同一个入口,以及同一套认证、权限与计费体系。
一个请求同时满足以下条件时按 WebSocket 处理:Connection 含 upgrade、Upgrade: websocket、Sec-WebSocket-Key 非空。
公共规则
| 项目 | 规则 |
|---|---|
| 认证 | 与 HTTP 相同,使用 Authorizationx-api-key 或 x-goog-api-key 请求头 |
| 单帧上限 | 16 MiB |
| 单连接时长 | 默认 60 分钟;阿里云 DashScope 的 Realtime 为 120 分钟 |
| 握手前失败 | 以 HTTP 状态码加纯文本返回,上游不可用时为 502 WebSocket upstream failure |
| 服务关闭中 | 503 Server is shutting down |
| 风控封禁 | 账号被临时封禁时,握手或后续请求以 403 拒绝,见《错误码》 |
浏览器无法为 WebSocket 设置自定义请求头,而 openai-insecure-api-key.* 子协议不会被当作凭证。浏览器端实时语音请使用 Realtime WebRTC 或由服务端代理连接。
Responses WebSocket 模式
与 OpenAI Responses WebSocket 模式语义一致:
wss://api.xairouter.com/v1/responses- 每个
response.create(以及response.steer)都会独立做准入:资源白名单、账号状态与额度、账号级限速、模型白名单与模型限额。 - 准入失败时,Router 发送一个错误事件后关闭连接:
{"type": "error", "status": 403, "error": {"message": "...", "type": "...", "code": "...", "status": 403, "retryable": false}}模型白名单或模型限额不通过时,此处一律为 403(HTTP 接口中模型限额返回 429)。
- 同一连接上排队等待的
response.create默认最多 8 个,且合计默认不超过 32 MiB;超出时返回可重试的错误事件,status为429、error.code为websocket_queue_full,连接保持可用。 - 粘性会话只依据握手请求头
session_id、conversation_id、session-id、thread-id。 - 首次连接上游时最多尝试 3 个上游。
- 每个 response 按上游返回的用量单独计费。
Codex 的 WebSocket 配置示例见《Codex CLI / App》。
Realtime
WebSocket
wss://api.xairouter.com/v1/realtime?model=<model>/realtime、/v1/realtime均可。模型来自查询参数model。- 每条连接在建立时做一次账号级限速检查。
- 支持 OpenAI 与阿里云 DashScope 的实时模型。
- 附着到已存在的 WebRTC 通话:
?call_id=<创建通话时返回的通话 ID>。Router 会校验通话属于当前账号且模型一致,找不到时返回404,模型不一致时返回409。
WebRTC 通话
POST /v1/realtime/calls- 请求体为 JSON 或 multipart,必须包含
sdp与session.model,大小不超过 4 MiB;只接受 POST,否则返回405。 - 请求体超过 4 MiB 或格式不合法返回
400 Invalid realtime call body。账号所在分组没有可用的实时语音上游时返回503(No available key或No available Realtime provider key)。 - 响应中的
Location被改写为/v1/realtime/calls/<通话 ID>,绑定有效期 65 分钟。服务端可用这个 ID 通过 WebSocket?call_id=附着到通话。
临时客户端密钥
POST /v1/realtime/client_secrets透传给上游。用于路由、权限与计费的模型名依次取请求体顶层 model、查询参数 model,都没有时为 gpt-realtime;session.model 不参与判断。
Live 会话
Live 是面向 gpt-live-1 的实时语音会话接口。Router 提供两种 Live 接入方式,分别对应不同的上游线路:
| OpenAI 官方 Live API | Codex Live V3 | |
|---|---|---|
| 对应套餐 | 上游为 OpenAI 官方 API 的套餐 | Codex 专营套餐 |
| 创建会话 | POST /v1/live/sessions(JSON),或 WebSocket 首帧 session.start | POST /v1/live(multipart 或 JSON,含 sdp 与 session) |
| 协议请求头 | 无 | openai-alpha: quicksilver=v2(必填) |
| 附着同一会话 | wss://api.xairouter.com/v1/live/sessions/{id}/attach | wss://api.xairouter.com/v1/live/{call_id} |
| 事件 | OpenAI 官方事件,如 session.input_transcript.delta | Live V3 事件,如 output_transcript.addedturn.done |
使用哪一种由账号所在套餐的上游线路决定;两种方式的请求体与事件不能混用。完整示例与报错对照见博客《gpt-live-1 两种调用方式》。
OpenAI 官方 Live API
按时长计费。WebRTC 会话在建会成功后起计 15 秒,之后按累计时长抵扣;主 WebSocket 按上游上报的秒数计费;委托给其他模型的 Token 与工具费用另计。
WebRTC(HTTP)
POST /v1/live/sessions请求体为 JSON,必须包含 session.model(非空,≤ 256 字节)、transport.type = "webrtc" 与 transport.sdp,大小不超过 4 MiB。
WebSocket
wss://api.xairouter.com/v1/live/sessions
wss://api.xairouter.com/v1/live/sessions/{id}/attach- 主连接升级后,须在 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 升级后发生的错误以错误事件与关闭帧报告。 - 账号级限速在
session.start时检查。 - 套餐上游不是 OpenAI 官方 API 时返回
503 No OpenAI Live project key at the configured model level,请改用 Codex Live V3。
Codex Live V3
POST /v1/live
wss://api.xairouter.com/v1/live/{call_id}- 请求体规则与 WebRTC 通话 相同:multipart(字段
sdp、session)或 JSON,必须包含sdp与session.model,不超过 4 MiB。 - 必须携带请求头
openai-alpha: quicksilver=v2,session中不要设置type字段。Router 原样转发这两项,相关错误由上游返回。 - 成功返回 HTTP
201,正文为 answer SDP,Location改写为/v1/live/<通话 ID>。sideband 使用该 ID 连接/v1/live/{call_id},携带相同的 Key 与协议请求头。 - 套餐上游不是 Codex 线路时,上游会返回
Your account does not have access to Quicksilver v2 sessions.,请改用 OpenAI 官方 Live API。
DeepSeek 语音合成 WebSocket
wss://api.xairouter.com/v1/tools/tts- 仅适用于 DeepSeek 模型,消息格式与 DeepSeek 官方一致。
- 认证可以使用请求头,也可以在浏览器中使用子协议:
Sec-WebSocket-Protocol: tts, bearer.<API Key>。该子协议凭证只对这一路由有效。 - 按客户端提交的累计字符数计费(汉字计 2 个字符):会话结束时只要已提交字符且未收到失败的
finish事件即计费,提前断开也可能计费。 - 请使用带
/v1的路径。