Realtime API 概述

更新时间:
复制 MD 格式

了解 Realtime API 支持的模型、接入方式、鉴权流程及现有教程和 Demo。

Realtime API 支持实时多模态交互、语音识别、语音合成、语音对话和音视频翻译。先查找所需模型支持的接入方式,再根据应用场景选择并进入对应的接入文档。

模型与协议支持

下表列出各模型和应用支持的协议。点击“支持”查看对应的接入文档。

模型/应用类型模型WebSocketWebRTCAOQ

实时全模态

qwen3.8-omni-flash-realtime、qwen3.5-omni-plus-realtime、qwen3.5-omni-flash-realtime

支持

支持

支持

实时语音合成

qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-flash、qwen-audio-3.0-tts-plus

支持

不支持

支持

CosyVoice系列模型

支持

不支持

支持

实时语音识别

qwen-audio-3.1-asr-flash-message、qwen-audio-3.1-asr-flash-streaming、qwen-audio-3.0-asr-flash-streaming、Fun-ASR-Realtime系列模型

Qwen-Audio-ASR-Message

Qwen-Audio-ASR-Streaming

Fun-ASR-Realtime

不支持

Qwen-Audio-ASR-Message

Qwen-Audio-ASR-Streaming

Fun-ASR-Realtime

实时语音对话

qwen-audio-3.1-realtime-plus、qwen-audio-3.1-realtime-flash、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash

支持

支持

支持

实时语音翻译

Qwen-Livetranslate-Realtime 系列模型

支持

支持

支持

多模态开发套件

multimodal-dialog

支持

支持

支持

说明模型的名称、上下文、价格、快照版本等信息请参见阿里云百炼控制台;并发限流条件请参考限流。

接入方式选择

Realtime API 支持 WebSocket、WebRTC 和 AOQ(AI over QUIC)三种接入方式。可用方式及输入、输出能力以所选模型的接入文档为准。

维度WebSocketWebRTCAOQ

适用场景

实时语音和多模态交互、服务端集成、快速原型验证

浏览器实时音视频交互、已有 WebRTC 基础设施的应用

需要弱网优化及音视频、模型事件协同传输的原生应用

浏览器兼容性

原生支持;需满足对应接口的鉴权要求

原生支持

当前 AOQ SDK 不提供浏览器接入

回声消除/降噪

由客户端使用的音频采集与处理组件提供

由浏览器或 WebRTC 客户端提供,依平台与配置而定

以所用平台的 AOQ SDK 音频配置为准

端侧平台支持

全平台(任何支持 WebSocket 的环境)

浏览器、移动端

移动端、桌面端和 Linux,详见 AOQ SDK 下载

Token Plan

支持

支持

支持

  • WebSocket:适用于实时语音和多模态交互、服务端集成及原型验证。通过 DashScope SDK 可快速实现实时语音对话。
  • WebRTC:适用于需要浏览器原生支持或已有 WebRTC 基础设施的实时音视频交互。
  • AOQ:AOQ 基于 QUIC,面向弱网下的实时交互进行优化,支持音视频与模型事件分轨传输,适用于需要集成媒体采集、编解码和播放能力的原生应用。

接入准备

确认调用地域和接入域名,获取该地域和业务空间对应的 API Key。

说明首次使用时,按控制台提示开通服务。创建后请立即复制并妥善保存 API Key,通过环境变量管理,勿嵌入客户端或提交到代码仓库。

使用 AOQ 时,按客户端平台下载 AOQ SDK。

鉴权方式

Realtime API 使用 API Key 进行身份认证。无论选择 AOQ、WebRTC 还是 WebSocket 协议接入,均通过 HTTP 请求头中的 Authorization 字段携带 Bearer Token 完成身份验证。

WebRTC 和 WebSocket 在建连时鉴权;AOQ 在 AppServer 请求连接凭证时使用 API Key 鉴权,客户端随后使用临时 Token 建连。连接建立后的数据传输无需重复鉴权。

建连鉴权详解

WebSocket

WebSocket 在建立连接时通过 HTTP 请求头携带 API Key 进行鉴权,具体要求参见对应模型的接入文档。

WebRTC

WebRTC 通过 HTTP POST 请求完成 SDP 交换,鉴权在此阶段完成。客户端将 Offer SDP 发送至服务端,服务端返回 Answer SDP。

AOQ

AOQ 采用服务端代理鉴权模式:API Key 仅在业务 AppServer 侧使用,客户端通过网关返回的临时 Token 建连,避免 API Key 暴露在客户端。

获取连接凭证

业务需要媒体连接时,由 AppServer 请求连接凭证并返回客户端,客户端随即调用 connect(config) 建连。

AOQ 即时鉴权与媒体建连时序

请求路径

模型系列建连请求路径
Qwen-Omni-Realtime、Qwen-Audio-Realtime、Qwen-Livetranslate-Realtime/api/v1/webrtc/realtime
Qwen-Audio-TTS、CosyVoice、Qwen-Audio-ASR-Streaming、Qwen-Audio-ASR-Message、Fun-ASR-Realtime/api/v1/webrtc/inference

请求说明

参数位置与类型说明

{endpoint}

URL · string

必填。使用所选地域和业务空间的接入域名。使用 Token Plan 时,域名中的 WorkspaceId 固定为 token-plan。

model

查询参数 · string

必填。待调用的模型 ID,建连路径按上表中的模型系列选择。

Authorization

请求头 · string

必填。格式为 Bearer <API_KEY>,使用与接入域名对应的 API Key。

Content-Type

请求头 · string

必填。固定为 application/json。

x-dashscope-rtc-transport

请求头 · string

必填。固定为 moq,指定使用 AOQ 协议。

clientIp

请求体 · string

选填。客户端真实公网 IP,用于选择 Relay 接入点;不传时使用请求来源 IP。

以下以 qwen3.8-omni-flash-realtime 为例,使用对应的 {endpoint} 和环境变量 DASHSCOPE_API_KEY。调用 Inference 路径的模型时,将请求路径改为 /api/v1/webrtc/inference,并设置对应的 model。

curl -X POST \
  "https://{endpoint}/api/v1/webrtc/realtime?model=qwen3.8-omni-flash-realtime" \
  -H "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "x-dashscope-rtc-transport: moq" \
  -d '{}'

返回说明

字段类型说明与 SDK 映射

sid

string

会话唯一标识,填入 AoqConnectConfig.sid。

aoqTokenForClient

string

客户端临时连接 Token,填入 AoqConnectConfig.token。

clientRelayEndpoints

array

Relay 接入点数组,填入 relayEndpoints。每项包含 endpoint、port 和 route_index;将 route_index 映射为 SDK 的 routeIndex,缺省时使用数组下标。

clientRelayCertFingerprint

string

Relay TLS 证书指纹,填入 AoqConnectConfig.certFingerprint。

sidExpiresInSecs

integer

会话有效期(秒)。过期后需重新获取,否则建立连接将失败。

extraInfo.workspaceIdHash

string

业务空间 ID 的哈希值,填入 AoqConnectConfig.workspaceIdHash。

以下为响应示例,字段值以实际返回为准。

{
  "sid": "<session_id>",
  "aoqTokenForClient": "<token>",
  "clientRelayEndpoints": [
    {"endpoint": "192.0.2.1", "port": 8443, "route_index": 0}
  ],
  "clientRelayCertFingerprint": "sha256/<fingerprint>",
  "sidExpiresInSecs": 7200,
  "extraInfo": {"workspaceIdHash": "<workspace_id_hash>"}
}

开发资源

WebRTC 教程

AOQ 教程与 Demo

使用 Android Demo 验证 AOQ 接入效果。扫描二维码下载 APK,安装后配置 API Key 和 workspaceId,即可体验 Demo 支持的部分模型。

AOQ Android Demo 下载二维码