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

# Realtime WebSocket API

> GA 会话配置、文字音频事件与终态判断。

`GET /v1/realtime`

## 握手与协议

连接占位 URL `wss://gateway.example.com/v1/realtime?model=YOUR_MODEL_ID`，用 WebSocket 客户端和 Bearer 网关令牌升级；model query 必填并由 URL 编码。请求无 JSON body，成功升级返回 HTTP 101；失败可能为 HTTP 4xx/5xx，升级后仍可能收到 error 或直接断开。

本站采用 GA 的 session 配置与 `response.output_*` 事件。OpenAI 适配器只对映射后名称含 `-realtime-preview` 的遗留模型附加上游 Beta 标识；这不代表自动转换事件结构。避免混合 Beta 的 modalities / input\_audio\_format / response.audio.delta 与本文 GA 字段。

## 客户端事件与字段

| 事件 | 常用字段及用途 |
| - | - |
| session.update | session.type=realtime；output\_modalities 选 text 或 audio；instructions、tools；audio.input / audio.output |
| conversation.item.create | item.type=message、role=user，content 中 input\_text；添加文本输入 |
| input\_audio\_buffer.append | audio 为原始音频字节的 Base64；不是媒体 URL 或 WAV 文件 |
| input\_audio\_buffer.commit | 提交累积音频；手动模式下仍需 response.create 才生成 |
| input\_audio\_buffer.clear | 清除未提交输入；不等于取消生成 |
| response.create | response 中按模型指定输出模态等配置；与 Responses 顶层 create 结构不同 |
| response.cancel | 请求取消活动响应；确认服务端终态，不等于停止本地播放 |
| conversation.item.truncate | 应用实现打断时按已播放位置同步音频项；需上游支持 |

字段以 [Realtime client events](https://developers.openai.com/api/reference/resources/realtime/client-events)为协议依据，网关和模型可能不支持全部扩展。本站脚本关闭工具和 VAD，每次只生成一轮，下面展示文字模式的三条独立消息：

```json theme={null}
{"type":"session.update","session":{"type":"realtime","output_modalities":["text"],"audio":{"input":{"format":{"type":"audio/pcm","rate":24000},"turn_detection":null}},"tools":[]}}
```

```json theme={null}
{"type":"conversation.item.create","item":{"type":"message","role":"user","content":[{"type":"input_text","text":"Hello"}]}}
```

```json theme={null}
{"type":"response.create","response":{"output_modalities":["text"]}}
```

## 服务端事件与关联

| 事件 | 意义 |
| - | - |
| session.created | 会话创建，读取 session.id 与协议类型 |
| session.updated | 有效配置回执；确认音频格式、模态和 turn\_detection |
| input\_audio\_buffer.committed | 输入音频已提交，包含 item\_id；不保证转写成功 |
| conversation.item.added / done | 对话项生命周期，不能替代生成完成 |
| response.created | 取得本轮 response.id |
| response.output\_text.delta / done | 文本增量和文本块结束 |
| response.output\_audio.delta / done | Base64 音频增量和音频块结束 |
| response.output\_audio\_transcript.delta / done | 输出音频的文字转录；不是音频字节 |
| response.done | 查看 response.status；completed、cancelled、failed、incomplete 不可混淆 |
| error / rate\_limits.updated | 请求错误 / 上游限制提示；不构成网关统一限额 |

内容事件使用 response\_id、item\_id、output\_index、content\_index 关联。最终 response.done 不含完整音频字节，要保留音频 delta。音频 done 也可能出现于非成功结束，必须继续核对最终状态。[服务端事件参考](https://developers.openai.com/api/reference/resources/realtime/server-events)给出完整上游结构。

## 音频格式与限制

示例请求 PCM16LE、24 kHz、单声道，配置为 `audio.input.format` / `audio.output.format` 的 `type: audio/pcm`、`rate: 24000`；音色位于 `audio.output.voice`。`turn_detection: null` 关闭自动 VAD，示例检查有效配置后才发送内容。其他格式、声音与采样率需模型支持，不能直接按 PCM WAV 保存。

后端可以施加连接时限、流空闲时限及实时请求限制。断开不保证业务成功，也不保证请求未执行；应用应保留完成状态和已播放位置，不自动重发音频。浏览器临时密钥、WebRTC、SIP 与 Live API 不属于此路由的自动兼容范围。

相关源码：`router/relay-router.go`、`relay/channel/openai/adaptor.go`、`relay/channel/openai/relay_realtime.go`，核对版本 `30a6d88a4`。此页使用可迁移 Markdown 描述握手与事件，不伪装成普通 JSON REST 操作。

[文字与音频可运行示例](/zh/guides/realtime) · [连接模块](/zh/guides/websocket)

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


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