WebSocket 与实时接口

WebSocket 与实时接口

长连接与实时语音场景与 HTTP 接口共用同一个入口,以及同一套认证、权限与计费体系。

一个请求同时满足以下条件时按 WebSocket 处理:Connection 含 upgrade、Upgrade: websocket、Sec-WebSocket-Key 非空。

公共规则

项目规则
认证与 HTTP 相同,使用 Authorization
x-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 APICodex Live V3
对应套餐上游为 OpenAI 官方 API 的套餐Codex 专营套餐
创建会话POST /v1/live/sessions(JSON),或 WebSocket 首帧 session.startPOST /v1/live(multipart 或 JSON,含 sdp 与 session)
协议请求头无openai-alpha: quicksilver=v2(必填)
附着同一会话wss://api.xairouter.com/v1/live/sessions/{id}/attachwss://api.xairouter.com/v1/live/{call_id}
事件OpenAI 官方事件,如 session.input_transcript.deltaLive V3 事件,如 output_transcript.added
turn.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 建会以 HTTP 400 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 的路径。

相关文档