OpenAI Realtime API 详解：端到端语音对话的原理、能力与接入

OpenAI 面向开发者的端到端语音对话入口是 Realtime API：应用建立持续连接，向模型传入声音，再接收模型生成的声音与控制事件。它适合能够接话、被打断、查询信息并执行工具的语音助手。

截至 2026 年 9 月 9 日，官方语音开发指南采用 gpt-realtime-2.1 作为对话示例模型。本文依据这一版本的文档介绍接口，附带 WebRTC 示例；模型价格和可用性以实际接入时的官方页面及项目权限为准。Realtime 概览

端到端语音对话的含义

从串联系统到原生音频输入输出

传统语音助手通常包含三个主要阶段：自动语音识别（ASR）把声音转换为文字，大语言模型（LLM）生成回答文字，语音合成（TTS）再将文字转换为声音。三个阶段可以分别流式运行，但应用需要协调识别结果、回答生成和音频播放。

原生语音路线由同一个对话模型直接处理音频输入和音频输出，应用不必先取得完整转写再提交给文字模型。OpenAI 将这一路线用于自然、低延迟的交谈；需要检查中间文字、复用既有文字助手的系统，则仍可采用串联架构。语音架构说明

从信息传递的角度看，音频包含语调、节奏和停顿，直接输入音频使模型有机会利用普通文字转写没有呈现的线索。这是架构上的解释，不能据此推导模型能够准确判断说话者的真实情绪。

“端到端”描述的是模型的输入输出路径。声音仍然需要采集、编码、传输和播放，系统仍然需要认证与业务逻辑。公开 API 文档不足以确定模型内部的音频编码器、离散音频表示、网络层数或训练配方，也不能据此断言其内部完全不使用文字表示。

一个直接证据是：Realtime 会话的输入转写默认关闭。启用转写后，它由独立服务异步产生；官方明确提示，转写只能辅助理解输入，不能当作模型实际听到内容的精确记录。输入转写契约

延迟来自整个交互链路

持续上传音频，使服务端能够在用户讲话期间接收输入；分段返回回答，使播放器无需等待整段语音生成完毕。一次接话的等待时间，可以用下面的工程模型分析：

从用户说完到听见回复的时间
≈ 判断本轮结束的时间
 + 剩余网络传输与服务排队时间
 + 模型生成首段音频的时间
 + 播放缓冲时间

这些阶段可能重叠，公式用于定位问题，不是服务端内部执行时序。端到端架构减少了应用必须协调的中间阶段，但真实延迟仍受网络、轮次判断、模型配置和设备播放影响。本文没有进行真实通话测速，也不将产品演示中的延迟视为 API 保证。

模型与接口的能力范围

对话模型与专项音频接口

“支持音频”并不意味着接口具有相同的交互方式：

需求	对应入口	返回行为
实时语音助手	Realtime 对话会话	生成回答、维护会话并调用工具
实时字幕	实时转写接口	随输入输出文字，不负责对话回答
持续口译	实时翻译接口	随源语音输出译文和翻译音频
朗读给定文本	Speech 接口	将应用提供的文字合成为声音
在既有请求中加入音频	支持音频的 Chat Completions 模型	按请求处理音频输入输出

这些是不同的模型与会话路径。例如，gpt-live-transcribe 面向实时转写，gpt-realtime-translate 面向持续翻译，不能直接替换对话示例里的模型名称。接口选择说明

当前对话模型

项目	GPT-Realtime-2.1	GPT-Realtime-2.1 Mini
模型标识	`gpt-realtime-2.1`	`gpt-realtime-2.1-mini`
输入	音频、文字、图片	音频、文字、图片
输出	音频或文字	音频或文字
上下文窗口	128,000 token	128,000 token
模型页标注的最大输出	32,000 token	32,000 token
推理能力	可配置推理强度	蒸馏推理模型
官方定位	改进字母数字识别、噪声处理和打断行为	更快、成本更低的实时交互

以上数值来自两者的模型页，不能套用旧版 gpt-realtime 的 32,000 上下文上限。两个模型都列出函数调用支持；视频输入、严格结构化输出与微调不在其当前支持范围内。2.1 模型说明、Mini 模型说明

图片输入适合补充截图或相机抓拍。例如，用户说“这个按钮有什么作用”，应用可以把对应截图加入会话；它不会因此自动获得持续视频或设备屏幕权限。

语音表现与推理配置

会话指令可以约束回答语言、长短和表达方式，例如“使用中文，每次回答两三句话，听不清时简短追问”。推理模型还可使用 reasoning.effort 调整计算投入。提高推理强度可能增加等待时间，应按任务成功率和延迟共同选择。

较长的查询过程中，可以要求模型先说一句具体进度，例如“正在查询这笔订单”。这类简短播报只用于说明正在执行的动作，不等于任务已经成功，也不是模型内部推理过程。实时模型提示指南

一轮语音对话的执行过程

会话、历史与回答

Realtime 使用有状态的事件协议。Session 保存模型和音频配置，Conversation 保存本次会话的输入输出条目，Response 表示一次回答生成。连接建立后，服务端发出 session.created；应用可以用 session.update 调整配置。会话对象说明

开启自动轮次检测后，典型流程如下：

持续输入音频
  → 检测用户开始讲话
  → 判断本轮结束并提交输入
  → 创建回答
  → 分段返回语音、字幕或工具调用
  → 回答结束，结果进入会话历史

这里是逻辑顺序。实际系统中音频播放、辅助转写和工具执行可以重叠，应用不能假设所有事件都按一个固定列表紧邻到达。

判断用户是否说完

VAD 是语音活动检测，例如识别此刻是否有人讲话。Realtime 提供两种轮次检测方式：

方式	判断依据	配置与取舍
`server_vad`	声音活动及持续静默	用 `threshold` 调整触发阈值，`silence_duration_ms` 调整等待静默的时长
`semantic_vad`	结合表达内容估计话语是否结束	用 `eagerness` 调整接话积极程度

例如，“帮我订明天去……嗯……杭州的票”中的停顿，不一定意味着说完。缩短静默等待通常让接话更快，也更容易提前截断句子；语义检测可以为未完成的表达等待更久。

create_response 控制检测到轮次结束后是否自动回答，interrupt_response 控制用户开口时是否取消当前回答。两者都设为 false 时，应用仍可接收 VAD 事件，再自行发送 response.create。VAD 配置说明

用户插话后的音频与历史同步

假设模型已经生成十秒回答，用户只听了前三秒就开始插话。系统需要同时处理：停止当前生成、清除未播放音频、让后续上下文反映实际播出的范围。

使用 WebRTC 或 SIP 时，服务端管理输出音频缓冲，并在自动打断时截断未播放部分。使用 WebSocket 时，应用管理播放器，需要停止播放并发送 conversation.item.truncate，其中 audio_end_ms 应来自已播放时长，而非已收到的音频长度。打断与截断说明

这也意味着：语音能够被打断，不代表后台业务已经取消。例如，用户打断一段订单说明时，是否还要取消订单查询，应由应用根据后续意图单独决定。

事件完成与业务成功的区别

response.done 表示本次回答生成结束，状态可能是 completed、cancelled、failed 或 incomplete。它不表示音频已全部播完，也不自动证明业务动作成功。

同样，response.function_call_arguments.done 在中断或取消时也可能出现。工具处理代码需要检查回答状态、参数完整性和当前任务是否仍然有效，再决定执行。服务端事件契约

三种连接方式

连接方式	适用位置	应用需要处理的内容
WebRTC	浏览器、移动客户端	麦克风授权、连接协商、控制事件及界面状态
WebSocket	应用服务器、自定义音频处理服务	音频格式、Base64 分块、播放缓冲与打断同步
SIP	电话与呼叫中心	SIP 路由、来电 webhook、接听和通话控制

官方建议浏览器和移动客户端优先采用 WebRTC。音频走媒体轨道，JSON 控制事件走数据通道；应用服务器可以仅参与初始连接协商。WebRTC 接入说明

服务端 WebSocket 连接使用 wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1。音频通过 input_audio_buffer.append 上传，输出音频从 response.output_audio.delta 接收；关闭 VAD 后，还需由应用提交输入并请求回答。WebSocket 接入说明

SIP 允许将电话接入同类会话。应用接收来电事件并调用接听接口，再通过服务端连接管理会话；电话号码、运营商线路和电话网络费用仍属于电话系统的部署范围。SIP 接入说明

WebRTC 最小接入示例

运行准备

本文示例使用浏览器原生 WebRTC 和 Node.js 内置 HTTP 服务，不依赖第三方包。完整文件可从这里下载：WebRTC 示例压缩包。解压后，在示例目录执行：

1
2
3

# 使用 Node.js 22 或更新版本
export OPENAI_API_KEY='替换为自己的 API Key'
node server.mjs

浏览器打开 http://localhost:3000，点击“开始对话”并允许使用麦克风。模型在用户说完后回答，页面展示助手字幕；“结束对话”关闭连接并停止麦克风。可选环境变量 OPENAI_REALTIME_MODEL 用于切换有权限使用的模型。

需要具有对应模型权限和可用 API 额度的 OpenAI 项目，以及可访问 API 的网络。实际通话产生 API 费用。示例用于本机学习；部署为公共服务时，还需加入用户认证、请求限流与用量控制。GitHub Pages 只托管文章和下载文件，不能运行示例里的 Node.js 服务。

服务端建立会话

示例采用官方的统一连接接口。浏览器先生成 SDP，即描述媒体连接参数的文本；服务端把 SDP 与以下配置一起提交到 /v1/realtime/calls：

const sessionConfig = {
  type: "realtime",
  model: process.env.OPENAI_REALTIME_MODEL || "gpt-realtime-2.1",
  output_modalities: ["audio"],
  reasoning: { effort: "low" },
  instructions: "你是中文语音助手。回答简短自然；听不清时请用户重复。",
  audio: {
    input: {
      turn_detection: {
        type: "semantic_vad",
        eagerness: "medium",
        create_response: true,
        interrupt_response: true,
      },
    },
    output: { voice: "marin" },
  },
};

服务端用 FormData 提交名为 sdp 和 session 的两个字段，长期 API Key 只保留在服务端。请求成功后，把返回的 SDP answer 交给浏览器，完成媒体连接协商。完整示例还处理了请求失败、超时和响应状态。统一连接接口说明

这里 output_modalities: ["audio"] 已包含音频对应的转录文本；当前接口不允许同时请求 ["text", "audio"]。这份输出字幕与前面提到的可选输入转写是两件事。会话配置参考

浏览器传输音频与处理事件

浏览器端的关键连接逻辑如下，完整的按钮状态、失败清理和字幕处理见下载文件：

const peer = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
stream.getTracks().forEach(track => peer.addTrack(track, stream));
peer.ontrack = event => { audio.srcObject = event.streams[0]; };

const events = peer.createDataChannel("oai-events");
events.onmessage = event => {
  const message = JSON.parse(event.data);
  if (message.type === "response.output_audio_transcript.delta") {
    // 将 message.delta 追加到对应回答的字幕区域
  }
};

const offer = await peer.createOffer();
await peer.setLocalDescription(offer);
const response = await fetch("/session", {
  method: "POST",
  headers: { "Content-Type": "application/sdp" },
  body: offer.sdp,
});
if (!response.ok) throw new Error(`会话创建失败：${response.status}`);
await peer.setRemoteDescription({ type: "answer", sdp: await response.text() });

WebRTC 音频由媒体轨道传输，这段代码不需要自行接收并拼接 Base64 音频。若浏览器阻止自动播放，可使用示例中的音频控件手动播放；离开 localhost 部署时，页面需要 HTTPS 和对应的麦克风权限。

临时凭证与 Agents SDK

另一种方式是：服务端调用 /v1/realtime/client_secrets 创建短期凭证，前端用它直接建立连接。凭证创建接口返回 value 和到期信息；到期时间约束的是创建新会话的能力，已经建立的会话可以继续运行。临时凭证仍属于访问凭证，应限制发放对象与频率。临时凭证参考

需要更高层会话管理时，官方 JavaScript Agents SDK 提供 RealtimeAgent 和 RealtimeSession。例如，安装 @openai/agents 后，可在浏览器构建项目中使用：

import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";

const assistant = new RealtimeAgent({
  name: "中文助手",
  instructions: "用中文简短回答，听不清时先追问。",
});
const conversation = new RealtimeSession(assistant, {
  model: "gpt-realtime-2.1",
});
await conversation.connect({ apiKey: ephemeralKeyFromYourServer });

这里的 ephemeralKeyFromYourServer 必须来自应用自己的服务端。SDK 减少了音频会话管理代码，账户认证、业务授权和持久化仍需由应用实现。Agents SDK 语音入口

工具调用与业务系统集成

函数调用的执行边界

语音助手要回答“我的订单到哪里了”，可以使用应用定义的 lookup_order 函数。模型生成函数名与参数，应用查询订单系统，再将结果作为 function_call_output 写回会话，并在需要继续回答时发送 response.create。

工具执行代码必须验证订单属于当前用户，检查参数，并区分“查询失败”和“订单不存在”。这些规则由服务端执行，提示词只用于说明模型应该如何选择工具和组织回答。

Realtime 还支持 MCP，即通过标准协议访问远端工具服务。使用普通函数工具时，执行动作的是应用；使用远端 MCP 工具时，Realtime API 负责连接工具服务，应用配置访问权限，并按需要处理批准请求。Realtime 工具说明

服务端控制连接

浏览器可以直接收发音频，应用服务器同时通过旁路控制连接加入同一个会话。WebRTC 建连响应的 Location 包含 call_id，服务器可据此连接：

1	wss://api.openai.com/v1/realtime?call_id=rtc_xxxxx

这条连接用于监听事件、更新指令和处理工具，使数据库凭证与业务代码保留在服务端。服务端控制说明

对较长任务，一种应用设计是让工具先返回任务标识，后台持续执行，语音助手根据真实进度继续回答。应用需要管理超时、重复调用和取消请求，避免把“停止播报”误当作“取消任务”。这是可采用的工程设计，本文下载示例仅实现语音连接，没有实现后台任务系统。

使用限制与工程取舍

会话时长与上下文不是永久记忆

官方会话指南当前规定单次 Realtime 会话最长 60 分钟。长期运行的设备需要重新建连，并由应用恢复必要的对话摘要与业务状态。

上下文达到输入上限后，默认机制会丢弃较早条目；关闭截断会使超限请求报错。128,000 token 是整体上下文窗口，不等于全部可用于历史输入，输出也需要预留空间。会话时长说明、上下文截断说明

文档还存在一个需要区分的层次：2.1 模型页标注最大输出 32,000 token，而通用会话参考对 max_output_tokens 的显式整数仍写为 1–4096，另可使用 "inf" 表示模型可用上限。因此，不能直接把 32768 或 32000 当作该字段的已验证合法参数；应按当前接口契约配置并确认返回状态。模型上限、参数契约

音频格式、音色与字幕

通过 WebSocket 发送裸音频时，当前支持的格式包括 24 kHz PCM、G.711 μ-law 和 A-law。不能把任意 MP3、WebM 文件字节标为 PCM 上传；WebRTC 示例由媒体协商处理音频传输。

内置音色包括 marin、cedar 等；模型在会话中首次输出音频后，不能再更换音色。自定义音色也有资格与授权录音要求，不是上传任意声音即可使用。音频配置、自定义音色说明

输入转写与回答生成异步进行，字幕到达时间不能作为可靠的轮次边界。发生打断后，字幕也不应被当作逐字对齐的播放记录。本文示例会为被取消的回答添加提示，但不尝试推算用户具体听到了哪一个字。

识别准确性与设备声学条件

噪声、远场拾音、口音和多人重叠讲话，都应进入实际设备测试。模型能完成中文对话，不代表它对每个方言、专有名词或中英混读场景具有相同准确率。

针对地址、邮箱和订单号，应要求逐项复述或借助屏幕确认；对含糊输入，应追问而非猜测。2.1 的字母数字识别改进不能替代业务校验。实体识别与模糊输入指导

外放设备还需要考虑回声消除，避免模型声音再次进入麦克风并触发打断。下载示例请求浏览器的回声消除与降噪能力，实际效果仍取决于浏览器和硬件。

权限、数据与服务可用性

长期 API Key 不能放入浏览器或公开固件。原生语音也不提供严格结构化输出保证，涉及业务动作的参数必须在服务端校验。请求速率与 token 吞吐量随模型、账户等级及项目配置而变，不能把创建会话的 RPM 直接理解为可同时支持的通话人数。模型能力与限额

OpenAI 文档说明，API 数据默认不用于训练，除非客户主动选择共享；默认滥用监控日志可能保留最多 30 天。零数据保留需要满足资格并启用相应控制，不能由“数据不用于训练”推导为“数据从不保留”。应用自己的录音、日志和第三方工具数据还需要单独管理。数据控制说明

成本估算与验证方法

当前价格

下表为调研日官方公布的美元价格，单位均为每百万 token：

模型	音频输入	缓存音频输入	音频输出	文字输入	缓存文字输入	文字输出
`gpt-realtime-2.1`	32	0.40	64	4	0.40	24
`gpt-realtime-2.1-mini`	10	0.30	20	0.60	0.06	2.40

图片输入另外计费：2.1 为 5 美元，缓存输入 0.50 美元；Mini 为 0.80 美元，缓存输入 0.08 美元，同样以百万 token 为单位。专项翻译或转写接口的计费口径可能不同，应查看对应模型价格。官方价格表

从音频时长到增量成本

官方成本指南给出的近似换算是：用户音频每 100 毫秒一个 token，助手音频每 50 毫秒一个 token。因此，新增一分钟用户语音约为 600 token，生成一分钟助手语音约为 1,200 token。音频 token 计费说明

据此计算两种模型处理“一分钟新增用户语音，加一分钟新生成助手语音”的音频成本：

GPT-Realtime-2.1
600 × 32 / 1,000,000 + 1,200 × 64 / 1,000,000 = $0.096

GPT-Realtime-2.1 Mini
600 × 10 / 1,000,000 + 1,200 × 20 / 1,000,000 = $0.030

这是根据公布费率计算的新增音频部分，不是每分钟通话包价。完整账单还会受到历史上下文再次作为输入、缓存命中、文字与推理输出、图片及可选输入转写等因素影响。连接保持空闲本身当前不收费；VAD 通常过滤空白音频，但手动把空白音频提交为会话输入则需另行考虑。成本组成说明

以实际会话记录验证方案

应用应记录 response.done 中的 usage，结合 API 用量记录统计成本。要评价用户体验，可以使用同一组设备和任务，记录下列指标：

指标	具体测量对象
接话延迟	用户真实说完到设备播放首段回复的时间，统计 P50、P95
打断延迟	用户开始插话到扬声器停止旧回答的时间
轮次判断	思考停顿被截断、说完后长时间不接话的比例
信息准确率	邮箱、地址、订单号等关键字段的正确率
任务完成率	工具调用是否执行成功，用户请求是否真正完成
会话成本	达成同一任务所产生的总费用

上述指标是应用侧的评估建议，不是 OpenAI 公布的服务承诺。只有在真实网络、拾音设备与业务工具上测量，才能判断 mini 模型是否足够，以及需要怎样调整轮次检测和推理强度。

本文示例按官方接口完成配置核对，并进行本地语法、页面构建及模拟上游的 HTTP 流程验证；未使用真实 API Key 发起通话。真实音频质量、延迟和账户可用性需要读者在自己的环境中验证。

击壤而歌