OpenAI Realtime API 怎么用？

官方资料（2026-10-31 核对）：Realtime API guide · WebRTC · WebSocket · Realtime conversations · VAD · API Pricing

先判断：Realtime、SSE 还是 Responses WebSocket？

已有文字应用先看 OpenAI API Streaming；工具链路很多再评估 Responses WebSocket。如果核心需求是语音打断、低首音频延迟和轮次检测，才进入本页架构。

浏览器安全建连：API Key 留在服务器

方案 A：服务端签发 client secret

1. 用户先登录你的应用，前端向自己的后端请求 Realtime 临时凭证。
2. 后端用标准 OpenAI API Key 创建 client secret，并把短期值返回给该用户。
3. 前端用 client secret 创建 WebRTC 连接；音频走 media track，控制事件走 data channel。
4. 工具调用、业务数据和权限判断仍回到后端，不把数据库凭证或私有逻辑放浏览器。

当前官方说明 client secret 默认有效 600 秒，可设置 10–7200 秒；到期前可创建多个会话，已创建的会话可继续。它仍需绑定用户、业务会话、速率限制与审计，不应写入永久缓存或分析日志。

方案 B：统一 WebRTC 接口

浏览器生成 SDP offer 发给你的后端；后端携带标准 API Key 把 SDP 与 session 配置转发到 /v1/realtime/calls，再把 SDP answer 返回浏览器。它减少前端直接接触临时凭证，但服务器必须校验用户、会话配置和允许的工具。

// 伪代码：只在受信任服务器创建短期凭证
const secret = await openai.realtime.clientSecrets.create({
  session: { type: "realtime", model: "gpt-realtime-2.1" }
});
return { value: secret.value }; // 不记录、不长期缓存

服务端 WebSocket：事件与音频都要自己管理

服务端可连接 wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1，使用标准 API Key 鉴权。连接建立后先收到 session.created，客户端发送 session.update，再等 session.updated 确认。不要在收到确认前假设配置已生效。

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "简洁回答；工具结果不确定时明确说明",
    "audio": {
      "input": { "format": { "type": "audio/pcm", "rate": 24000 } },
      "output": { "format": { "type": "audio/pcm", "rate": 24000 } }
    },
    "turn_detection": { "type": "server_vad" }
  }
}

PCM 配置当前为 24 kHz、单声道。WebSocket 输入通过 input_audio_buffer.append 发送 Base64 音频，每个事件的音频块上限为 15 MB；输出音频从 response.output_audio.delta 持续读取，done 事件不再携带音频字节。生产中应使用更小、稳定的帧并监控发送队列，避免大块数据造成抖动。

理解状态：Session、Conversation 与 Response

• Session：连接级模型、指令、音频格式、VAD、工具和输出配置；当前最长 60 分钟。
• Conversation：按顺序保存用户、助手与工具 Items；它不是你的永久业务数据库。
• Response：一次模型输出，可含音频、转写、文本或函数调用。以完成/取消/失败事件判断终态。

一旦会话已经输出过音频，当前 voice 不能在同一 session 中更换；需要换音色应创建新会话。output_modalities 可选择音频（含 transcript）或文字，不能同时请求两种独立输出。长会话要把业务状态、用户授权和可恢复摘要保存在后端，并在接近 60 分钟时平滑重连。

VAD、按键说话与语音打断

server_vad 与 semantic_vad

server_vad 根据音量与静音判断说话开始/结束，是语音会话默认起点；semantic_vad 根据话语是否像“说完了”决定等待，可通过 eagerness 调整抢答与等待的平衡。两者都应监听 input_audio_buffer.speech_started 与 speech_stopped，并用真实口音、噪声和网络延迟测试。

Push-to-talk

把 turn_detection 设为 null，按下时必要时发送 response.cancel 并清空旧缓冲，松开时提交 input_audio_buffer.commit，再发送 response.create。按键模式更可控，但界面必须明确录音状态、取消与错误。

WebSocket 打断必须对齐“实际听到的位置”

1. 收到用户开始说话事件，立即停止本地播放并发送 response.cancel。
2. 记录上一条助手音频实际播放到的毫秒位置，而不是已下载字节数。
3. 发送 conversation.item.truncate，带上对应 item 和 audio_end_ms。
4. 等待终态，确认 response.done 的状态为 cancelled，再继续新回合。

WebRTC/SIP 可由服务端自动截断未播放音频；WebSocket 客户端若只停播放器不 truncate，后续模型可能基于用户没有听到的内容继续回答，造成上下文错位。

工具调用：模型决定调用，后端决定是否执行

在 session 中声明函数名称、描述与 JSON Schema。模型返回函数调用参数后，后端必须验证参数、登录用户、资源权限、幂等键和超时；执行结果作为工具 item 写回，再触发后续 response。不要让浏览器直接执行退款、发信、下单或数据库修改。

完整的参数校验与回传模式见 OpenAI Function Calling 指南。

安全、隐私与可观测性

• 身份：服务端签发临时凭证前验证登录态；向 API 传稳定、不可逆的安全标识，例如内部用户 ID 的哈希。
• 最小暴露：标准 Key、工具密钥、数据库与管理接口全部留在后端；client secret 只短期使用。
• 同意：麦克风开启、录音/存储、人工复核和删除策略应对用户可见，并符合所在地区要求。
• 失败路径：记录 session/request/response/call_id、错误类型、重连、取消和工具耗时，但不把秘密或原始敏感音频写进普通日志。
• 指标：P50/P95 首音频时间、打断成功率、空响应率、重连率、工具成功率、每成功会话成本和人工转接率。

速率与故障排查可结合 429 限制指南和 5xx/超时指南。

模型与成本：用真实会话评测

当前官方价格页列出 gpt-realtime-2.1 与较低成本的 mini 版本，并分别计费音频、文本、缓存和图像 Token。价格和模型目录可能变化，所以页面不把报价写进架构常量：上线前在官方 Pricing 与模型目录复核，再用真实口音、环境噪声、打断、工具回合与业务成功率比较。

上线前检查清单

1. 浏览器源码、Network、日志和错误上报中都没有标准 API Key。
2. WebRTC/WebSocket 的建连、失败、重连、60 分钟收尾和撤销权限均测试。
3. server_vad、semantic_vad、push-to-talk 与真实噪声场景分别评测。
4. 用户打断后本地播放停止，WebSocket truncate 的毫秒位置与会话上下文一致。
5. 所有工具参数、权限、幂等、超时和人工确认均由后端控制。
6. 音频格式、采样率、队列背压、取消、错误与终态都有明确状态机。
7. 安全标识、隐私告知、数据保留、监控告警与成本预算完成评审。

常见问题