OpenAI Realtime API

核心思想

Realtime API 面向低延迟、持续双向的会话。客户端与服务端交换事件，而不是每一轮都等待完整 HTTP 响应。它适合语音助手、实时翻译、呼叫处理和需要快速打断的多模态体验。

传输选择

• WebRTC：浏览器和移动客户端的实时媒体首选，适合音频轨道与低延迟交互。
• WebSocket：服务端到服务端或需要自行处理音频流和事件的场景。
• SIP：电话网络接入场景，具体能力以当前官方文档为准。

不要在浏览器中暴露长期 API key。客户端连接应通过后端签发短期凭据或官方推荐的安全会话建立方式。

会话与事件

应用通常需要处理：会话配置、音频缓冲、用户输入转录、response 创建、音频增量输出、工具调用、取消与错误。因为事件可交错到达，必须用事件 ID、item ID 和 call ID 正确关联状态。

语音产品的额外难点

1. 打断：用户说话时要停止未播放的响应，并同步服务端与播放器状态。
2. 端点检测：自动 VAD 与手动 push-to-talk 的体验和误触发不同。
3. 延迟预算：网络、编码、VAD、模型首包和播放缓冲都影响体感。
4. 隐私：明确录音、转录、保留与人工复核政策。
5. 工具副作用：语音误识别不能直接触发高风险写操作，应复述关键参数并确认。

验收指标

不仅测“能否对话”，还要记录首音频延迟、打断成功率、转录错误率、工具成功率、无声/噪声恢复、单会话成本和异常断线恢复。

相关笔记

• responses-api
• [[speech-to-speech-model]]
• [[voice-agent]]
• openai-agent-evaluation-and-tracing

官方资料

• Realtime API guide
• Realtime conversations
• Realtime API Reference