Responses WebSocket API

握手、create 字段、事件关联和当前网关限制。

GET /v1/responses

​

握手

通过 WebSocket 客户端升级连接，URL 使用 wss://gateway.example.com/v1/responses（占位地址），附加 Authorization: Bearer YOUR_API_KEY。没有 HTTP JSON 请求体；WebSocket 库负责 Upgrade、Connection、Sec-WebSocket-Key 和版本头。成功为 HTTP 101；失败可能是 400 / 401 / 403 / 429 / 5xx 或代理响应。

模型在首个 create 事件中提供，握手后才进行渠道选择。每个 create 都会重新执行请求认证和限流。必须有支持该协议并启用 ResponsesWebSocketEnabled 的渠道。此 GET 不用于查询资源，查询插件任务请用带 ID 的 GET。

​

客户端消息

字段 / 事件	说明
type = response.create	创建一轮生成；常用字段直接放在事件顶层
model	本次请求模型；连接建立上游后不能切换模型
input	新输入；示例采用完整显式历史
instructions / tools / include	常用 Responses 字段，依模型和渠道保留能力
previous_response_id	上游续接状态标识；不保证重连或跨渠道恢复
store	上游请求选项；不构成数据保留策略
event_id	客户端事件标识；网关错误可回显，不保证普通上游事件回显
stream_id	可作为关联字段；当前网关仍只允许一个活动生成，不能启用多路并发
generate	可转发的预热扩展；不是示例支持的流程，需上游验证
response.cancel	对活动生成发送控制，等待上游结果；不是 REST cancel

当前解析器也接受 create 的 response 包装对象；示例固定采用顶层结构，不混用两种形式。stream、background、stream_options 不作为传输配置转发；连接本身使用事件。常用字段含义参见创建响应，不能由此推断所有 HTTP 扩展等价可用。

以下是独立消息示意，cancel 中 ID 需来自正在生成的响应：

{"type":"response.create","model":"YOUR_MODEL_ID","input":[{"role":"user","content":"Hello"}],"store":false}

{"type":"response.cancel","event_id":"cancel_1","response_id":"resp_CURRENT"}

​

服务端消息

事件	客户端处理
response.created	取得 response.id，建立本轮关联
response.output_item.added / done	输出项生命周期；保留完整结果结构
response.output_text.delta	按 item_id、output_index、content_index 合并 delta；response_id 可能不出现
response.output_text.done	单个文本块结束，不代表整轮成功
response.completed	核对 response.id、status=completed、output 及内容状态
response.done	网关也识别的终态别名；检查 status，不能仅按事件名认定成功
response.failed / incomplete / cancelled / canceled	非成功终态；不发布为完整结果
error	网关错误可含 status、event_id、stream_id、response_id、error；上游结构可能不同

增量事件和最终对象使用 Responses 结构，而不是 Chat choices 或 Realtime session。示例收集结果后才输出，并拒绝工具和拒答。完整函数循环仍需应用侧实现。标准事件背景见 Responses streaming events。

​

限制与错误恢复

重叠发送 create 可能收到携带 409 的 error 事件。一次成功握手不意味着后续认证、限流或已锁定渠道一直有效。活动任务只允许有限的待处理控制；取消可能单独报错。配置变更或上游连接变化可能要求重新连接。

Socket 关闭、未收到终态、error 或本地超时都不代表生成成功。不能把 SDK 官方多路会话、重连缓存或 60 分钟寿命直接视作网关保证；部署还可能施加更短超时。相关源码：router/relay-router.go、controller/responses_websocket.go、relay/responses_websocket.go，核对版本 30a6d88a4。

可运行示例 · 共用连接模块

Read in English