> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/zh/api-reference/responses-retrieve)。

## 客户端消息

| 字段 / 事件 | 说明 |
| - | - |
| 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` 不作为传输配置转发；连接本身使用事件。常用字段含义参见[创建响应](/zh/api-reference/responses)，不能由此推断所有 HTTP 扩展等价可用。

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

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

```json theme={null}
{"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](https://developers.openai.com/api/reference/resources/responses/streaming-events)。

## 限制与错误恢复

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

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

[可运行示例](/zh/guides/responses-websocket) · [共用连接模块](/zh/guides/websocket)

[Read in English](/en/api-reference/responses-websocket)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.