简介
Realtime API 提供低时延的文本/语音实时对话能力,通过 WebSocket 建立长连接,按事件流交互。支持文本和音频两种输入输出模式,可实现实时语音对话、文本对话等功能。
接口地址:
认证
Bearer Token,如 Bearer sk-xxxxxxxxxx
连接参数
模型名称,支持的模型:
gpt-realtime - GPT Realtime 标准版
gpt-realtime-mini - GPT Realtime Mini 版
基础信息
事件类型
客户端发送事件
服务端返回事件
会话配置
建立 WebSocket 连接后,首先需要发送 session.update 事件来配置会话参数。
会话配置示例
会话参数说明
支持的交互模式,可选值:
"text" - 文本模式
"audio" - 音频模式
可同时包含多个模式,如 ["text", "audio"]
语音类型,可选值:alloy、echo、fable、onyx、nova、shimmer
温度参数,控制输出的随机性,范围:0.0 - 2.0
输入音频格式,目前仅支持 pcm16
输出音频格式,目前仅支持 pcm16
工具选择策略:auto、required、none
发送消息
文本消息示例
音频消息示例
音频消息需要先通过 input_audio_buffer.append 推送音频数据,然后调用 input_audio_buffer.commit 提交:
请求生成回复
发送消息后,需要调用 response.create 来触发生成:
完整示例
Python 示例
JavaScript 示例
响应示例
错误处理
错误事件格式
常见错误
音频格式要求
输入音频
- 格式:PCM16(16-bit PCM)
- 声道:单声道(Mono)
- 采样率:24000 Hz
- 编码:Base64 编码后通过
input_audio_buffer.append 发送
输出音频
- 格式:PCM16(16-bit PCM)
- 声道:单声道(Mono)
- 采样率:24000 Hz
- 编码:Base64 编码,通过
response.audio.delta 事件返回
使用流程
- 建立连接:通过 WebSocket 连接到
wss://vera-hub.ai/v1/realtime?model={model}
- 配置会话:发送
session.update 事件配置会话参数
- 发送消息:
- 文本模式:发送
conversation.item.create 事件
- 音频模式:先发送
input_audio_buffer.append 推送音频,然后 input_audio_buffer.commit 提交,最后发送 conversation.item.create
- 请求回复:发送
response.create 事件触发生成
- 接收回复:监听
response.text.delta 或 response.audio.delta 事件接收增量输出
- 完成处理:收到
response.done 事件后,可查看 usage 统计信息
注意事项
- 必需步骤:建立连接后必须先发送
session.update 配置会话
- 触发回复:发送消息后必须调用
response.create 才能触发生成
- 音频格式:音频必须为 PCM16 单声道 24000Hz,Base64 编码
- 事件 ID:建议为每个事件设置唯一的
event_id,便于追踪和调试
- 连接管理:保持 WebSocket 连接活跃,避免频繁断开重连
- 错误处理:监听
error 事件并实现适当的错误处理逻辑
- 依赖库:
- Python:
pip install websocket-client
- JavaScript: 使用原生
WebSocket API 或 ws 库
最佳实践
- 连接复用:尽量复用同一个 WebSocket 连接进行多轮对话,减少连接开销
- 错误重试:实现指数退避重试机制处理网络错误
- 音频缓冲:音频数据建议分块发送,避免单次发送过大
- 使用统计:关注
response.done 中的 usage 信息,合理控制成本
- 超时处理:设置合理的超时时间,避免长时间等待