概述
Realtime 是一类走 WebSocket 长连接的语音模型:音频流进、音频流出,中途可以被打断,不需要「录完再上传、等一段再播放」。它和「ASR + 文本模型 + TTS」三段式拼接的最大区别是端到端——模型直接听到语气、停顿和情绪,也直接说出来,延迟能压到亚秒级。 目前 API易 接入了 4 个模型、2 套协议,共用同一条端点和同一把令牌:gpt-realtime-2.1/gpt-realtime-2.1-mini—— OpenAI Realtime GA 协议qwen3.5-omni-plus-realtime/qwen3.5-omni-flash-realtime—— 阿里云百炼协议
server_vad 与 semantic_vad 两种自动断句、Function Calling 全链路(含结果回注)、图片输入、usage 按模态分列。四个模型的上述能力均已逐项实测通过(2026-08-24 (UTC+8))。model 参数、不改请求体字段,一定连不通——这是接入本能力最高频的失败原因。差异只有 6 个字段 + 3 个事件名,全部列在下方「两套协议对照」一节。申请内测开通
API 使用手册
令牌与分组管理
调用日志查询
让 AI Agent 帮你接入
.md),再按你项目的技术栈写代码——两套协议的字段族、采样率红线、打断收口、空闲断线这几个高频问题已经写死在要求里。让编程 Agent 接入或排查 Realtime 实时语音。复制后直接粘贴给 Codex、Claude Code、Cursor 等。
这段提示词替你挡掉了什么
这段提示词替你挡掉了什么
为什么选 API易 的 Realtime 语音
一把令牌,四个模型
wss 端点、同一套鉴权,换模型只改 model 参数与对应字段模板,不用维护两家账号体系。国内直连,免出海
api.apiyi.com,无需注册上游厂商账号、无需实名与预充值。两套协议差异已替你测完
文本通道可零成本自测
实测延迟与并发有据可查
内测期直连技术支持
核心特性
双向流式 · 可打断
response.cancel 打断当前回复,会话不中断、上下文不丢。四个模型均实测通过。两种自动断句
server_vad 按静音时长断句,semantic_vad 按语义意图断句(更能忽略「嗯」「对」这类附和声)。两种在四个模型上均实测通过。Function Calling 全链路
function_call_output 回注结果 → 模型接着说。四个模型的完整链路均实测通过。图片输入 · 分模态计量
usage 把文本 / 音频 / 图片 token 分列返回,成本可归因。四个模型均实测通过。支持的模型
模型定价
gpt-realtime-2.1 为例,音频输入 $32 对文本输入 $4,音频输出 $64 对文本输出 $24)。所以联调阶段应该跑纯文本,等链路确认无误再接音频——具体做法见下方「先用文本跑通」一节。Realtime GA 协议
阿里云百炼协议
计费维度与上表不同:图片输入并入文本档,输出侧只区分「纯文本」与「文本+音频」(后者只对音频部分计费)。分组介绍
技术规格
实测延迟与并发
2026-08-24 (UTC+8) 经api.apiyi.com 公网路径实测,20 路并发 × 2 模型,单轮纯文本问答:
端点一览
model 查询参数决定路由到哪个模型。
⚠️ 两套协议对照(迁移必读)
两个家族的端点、鉴权、整体事件流程完全一致,差异集中在session.update 的字段结构和几个服务端事件名上。
请求体字段对照
服务端事件名对照
session.created / session.updated / conversation.item.create / input_audio_buffer.append / input_audio_buffer.commit / response.create / response.cancel / response.done 等其余事件名两套一致。
两段最小 session.update
同一件事各写一遍,可以直接抄。阿里云百炼协议:先用文本跑通:文本通道的意义与三级自测阶梯
音频链路要调麦克风采集、重采样、分片、断句,任何一环出错都表现为「没反应」,很难定位。所以不要一上来就接麦克风。文本是控制面,不是备选输入
在实时语音模型里,文本不是「音频之外的另一种输入方式」,而是除音频流以外的全部控制通道:三级自测阶梯
第一级:纯文本,不碰麦克风
output_modalities 只留文本、关掉自动断句,发一条 input_text 就能验证:握手通不通、令牌与分组对不对、字段模板选对了没有、session.update 有没有生效、工具能不能回注、多轮上下文在不在、并发扛不扛得住。完全不产生音频 token。第二级:回放本地 wav 文件
input_audio_buffer.append。这一步把音频链路(格式、采样率、分片、commit、VAD 触发)与业务逻辑解耦,可重复、可回归——同一个文件跑两次结果应该一致。第三级:接实时麦克风
一段能跑的文本冒烟脚本
只依赖websockets(pip install websockets)。改 FAMILY 一个变量就能在两套协议之间切换:
会话能力:音色 · 断句 · 工具 · 图片
音色
断句:server_vad 与 semantic_vad
server_vad—— 按静音时长断句,参数直观(threshold、silence_duration_ms、prefix_padding_ms)。semantic_vad—— 按语义意图断句,能忽略「嗯」「对」这类附和声和无意义背景音,多人环境更稳。- 也可以把断句关掉(传
null或none)走手动模式:自己发input_audio_buffer.commit再发response.create,适合「按住说话」这类由 UI 控制轮次的交互。
工具调用
事件顺序:模型输出function_call 类型的 response.output_item.done(其中带 call_id 和 arguments)→ 客户端执行 → 回注结果 → 再次 response.create 让模型接着说。
图片输入
Realtime GA 协议:直接在消息里放input_image,值可以是 data URI。
Error append image before append audio.。实测做法是把 input_image_buffer.append 按约每秒一帧交织进 input_audio_buffer.append 序列里。
已知限制与规避(内测期)
以下四条均为实测结论,且都会打到客户端代码,接入前请先看一遍。最佳实践
先按协议家族选字段模板
session.update 写成两个配置常量,按模型名选择,不要用 if 到处打补丁。这是最容易在半年后维护出错的地方。首帧一次性定死会话参数
output_modalities、voice、speed、turn_detection、transcription 在第一条 session.update 里全部设好。音色尤其如此——出过音频再改就晚了。纯文本冒烟通过再接音频
采样率与声道在客户端转好
用 output_item.done 加超时收口
response.done。这样写在两个家族上都正确,也避免打断时把一轮挂住。长会话做保活与重连
expires_at。重连之后必须重放 session.update 与必要的上下文,否则新会话是默认配置。生产走后端中继
错误码与重试
event_id 与会话的 session.id,反馈问题时附上,能大幅缩短定位时间。另外 Realtime GA 协议的错误对象带 code 与 param 字段(会明确指出是哪个字段、支持哪些取值),百炼协议的错误信息相对粗一些,调试期优先在前者上验证字段写法。常见问题
为什么这一页没有在线 Playground?
为什么这一页没有在线 Playground?
四个模型能只改 model 名互相替换吗?
四个模型能只改 model 名互相替换吗?
modalities ↔ output_modalities、voice ↔ audio.output.voice、input_audio_format ↔ audio.input.format、turn_detection ↔ audio.input.turn_detection、input_audio_transcription ↔ audio.input.transcription,以及 response.text.delta ↔ response.output_text.delta、response.audio.delta ↔ response.output_audio.delta 两个事件名。完整对照见下方「两套协议对照」一节。握手就失败 / 连不上,怎么排查?
握手就失败 / 连不上,怎么排查?
https://,应该是 wss://;② 端点有没有带 ?model=<模型名>;③ Authorization: Bearer <令牌> 请求头有没有带上;④ 令牌是否已开通内测分组(没开通会返回 503 提示无可用渠道);⑤ 中间有没有反向代理吃掉了 Upgrade 头——自建网关转发时这一点很常见。浏览器能直连吗?令牌会不会泄露?
浏览器能直连吗?令牌会不会泄露?
Sec-WebSocket-Protocol 子协议形式的鉴权,浏览器 WebSocket 构造函数可以直接连上。但这等于把令牌发给浏览器,任何访问者都能从网络面板读到,只建议用于本机验证。生产环境请写一个后端中继:后端持有令牌并建立到 API易 的连接,前端只与你自己的服务通信。给 gpt-realtime-2.1 传 16 kHz 音频报错?
给 gpt-realtime-2.1 传 16 kHz 音频报错?
integer_below_min_value。正确写法是 "audio": {"input": {"format": {"type": "audio/pcm", "rate": 24000}}}。阿里云百炼协议那两个模型则要求 16 kHz,两套不能混用。没有麦克风 / 音频不好测,怎么办?
没有麦克风 / 音频不好测,怎么办?
say + afconvert 一行生成,命令见该节。发了 response.cancel 之后一直等不到 response.done?
发了 response.cancel 之后一直等不到 response.done?
response.text.done、response.content_part.done、response.output_item.done,但不再下发 response.done。请改用 response.output_item.done 作为一轮结束的判据,并加超时兜底。 会话本身不受影响,打断后可以继续正常对话。Realtime GA 协议那两个模型此处表现正常。连接大约 5 分钟就断了?
连接大约 5 分钟就断了?
session.update)保活,或者接受断线并实现自动重连。重连后记得重放 session.update 与必要的上下文。一个会话最长能开多久?
一个会话最长能开多久?
session.created 事件里带 expires_at 字段,实测约为建连后 30 分钟,到期需要重连。阿里云百炼协议侧我们主要观测到的是空闲 300 秒断开这一约束。长通话请按「会话会到期」来设计,做好跨会话的上下文续接。音色怎么设?为什么中途改音色报 cannot_update_voice?
音色怎么设?为什么中途改音色报 cannot_update_voice?
session.update 里设:百炼协议是顶层 voice,Realtime GA 协议是 audio.output.voice。一旦会话中已经产生过音频输出,就不能再改音色,这是两套协议共有的限制,会报 cannot_update_voice。请在首帧就定死,要换音色请新开会话。另外百炼协议不要传空字符串音色,会触发 400。手动 commit 模式下拿不到输入转写文本?
手动 commit 模式下拿不到输入转写文本?
flash 型号在手动 commit 模式下不会下发转写的完成事件(多次测试稳定复现),plus 型号正常,两者在 VAD 模式下都正常。推荐改用 server_vad 或 semantic_vad 模式。实测发现转写文本此时落在增量事件的一个未公开字段里,但该字段随时可能变化,不建议依赖。注意这只影响「在界面上回显用户说了什么」,不影响对话本身——模型对音频内容的理解与回答是正确的。支持图片输入吗?为什么报 Error append image before append audio.?
支持图片输入吗?为什么报 Error append image before append audio.?
input_image;阿里云百炼协议把图片当作视频帧处理,必须先追加音频再追加图片,否则就会报这个错。实测做法是按约每秒一帧,把图片交织进音频分片序列里。有 Prompt 缓存吗?怎么确认命中?
有 Prompt 缓存吗?怎么确认命中?
usage 的 input_token_details.cached_tokens 会有值。阿里云百炼协议那两个模型目前未观察到缓存命中。成本怎么估?文本和音频是分开算的吗?
成本怎么估?文本和音频是分开算的吗?
response.done 事件的 usage 字段按模态分列返回(文本 / 音频 / 图片,输入输出各一组),可以据此归因。音频档位显著高于文本,所以联调期建议跑纯文本。准确扣费请以控制台调用日志为准。