全部產品
Search
文件中心

Alibaba Cloud Model Studio:Qwen-Audio-Realtime AOQ 接入

更新時間:Nov 16, 2026

Qwen-Audio-Realtime AOQ 接入

AOQ 將音訊媒體與模型事件分軌傳輸。SDK 負責音訊採集、編解碼、傳輸和播放;應用透過 Data 軌發送模型事件並處理回覆。本頁使用 Qwen-Audio-Realtime 的媒體方向和事件協議。

適用範圍

本文面向 Qwen-Audio-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-audio-3.1-realtime-plus。

  • 使用所選地域和業務空間對應的 API Key 與 Workspace ID。

  • 北京域名:{WorkspaceId}.cn-beijing.maas.aliyuncs.com;新加坡域名:{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com。

  • API Key 只保存在服務端,不放入瀏覽器或移動端應用。

  • 使用麥克風采集音訊時,按平台要求申請麥克風權限。

  • 從 SDK 下載獲取對應平台的 SDK。

鑒權與連接憑證

說明如需預先取得 Token,或瞭解完整的鑒權流程,請參見建連鑒權詳解。

由業務 AppServer 發起以下請求。請先配置 API Key 到環境變量。在下方請求地址選擇地域,並填寫業務空間 ID。clientIp 選填,不填時使用請求網關的 IP。

POSThttps://WorkspaceId.cn-beijing.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plus
POSThttps://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plus

export ENDPOINT="{WorkspaceId}.cn-beijing.maas.aliyuncs.com"
curl -X POST \
  "https://${ENDPOINT}/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plus" \
  -H "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "x-dashscope-rtc-transport: moq" \
  -d '{}'

如需指定用戶端公網 IP,將請求體中的 -d '{}' 替換為 -d '{"clientIp":"<客户端公网 IP>"}'。

參數說明

配置項

值

說明

endpoint

根據業務情況選擇接入域名

指定對應的接入域名,詳情請參見選擇地域、服務部署範圍和接入域名。如果使用Token Plan,接入域名中的 WorkspaceId 固定為 token-plan。

Content-Type

application/json

指定消息類型

Authorization

Bearer <YOUR_API_KEY>

填寫API Key

x-dashscope-rtc-transport

moq

指定使用 AOQ 協議

clientIp

用戶端真實公網 IP

選填。不填寫時,預設使用請求百鍊網關的 IP;填寫後以 clientIp 為準。服務 會根據用戶端 IP 分配最佳的 Relay 接入點

響應示例

{
    "sid": "1d06b55683db49bba67a407902f62d02:1782706970:69aecdc5...",
    "aoqTokenForClient": "ecc1a46015d5496ca4ff7a48281eb739",
    "clientRelayEndpoints": [{"endpoint": "121.199.XX.XX", "port": 8443, "route_index": 0}],
    "clientRelayCertFingerprint": "sha256/99843495...",
    "sidExpiresInSecs": 7200,
    "extraInfo": {"workspaceIdHash": "2021b6f98cea4cff"}
}

響應參數說明

欄位

說明

sid

會話唯一標識

aoqTokenForClient

用戶端連接令牌,傳給 SDK 的 token 欄位

clientRelayEndpoints

Relay 接入點陣列。響應示例中的陣列元素包含以下欄位:

屬性

endpoint

Relay 接入點地址。

port

Relay 接入點端口。

route_index

下方 iOS 示例在該欄位缺省時使用陣列下標。

clientRelayCertFingerprint

Relay TLS 證書指紋

sidExpiresInSecs

會話過期時間(秒)

extraInfo

附加資訊。

屬性

workspaceIdHash

工作區 ID 哈希。

AOQ Client SDK 連接示例

說明clientIp 為請求體中的選填欄位。不填寫時,預設使用請求百鍊網關的 IP 作為用戶端 IP;填寫後則以指定的 clientIp 為準。建議由業務 AppServer 獲取用戶端真實 IP 後填入,以獲得最佳的 Relay 接入點。

let resp = try JSONDecoder().decode(AllocateResponse.self, from: responseData)

let config = AoqConnectConfig()
config.token = resp.aoqTokenForClient
config.sid = resp.sid
config.certFingerprint = resp.clientRelayCertFingerprint
config.relayEndpoints = resp.clientRelayEndpoints.enumerated().map { index, item in
    let ep = AoqRelayEndpoint()
    // route_index 缺省时按数组下标兜底
    ep.routeIndex = item.routeIndex ?? index
    ep.endpoint = item.endpoint
    ep.port = item.port
    return ep
}
config.workspaceIdHash = resp.extraInfo?.workspaceIdHash ?? ""

let audioTrack = AoqTrackParam()
audioTrack.trackType = .audio
let dataTrack = AoqTrackParam()
dataTrack.trackType = .data
config.publishTracks = [audioTrack, dataTrack]
config.subscribeTracks = [audioTrack, dataTrack]

engine.connect(config)
JSONObject obj = new JSONObject(responseText);
AoqClientEngine.AoqConnectConfig cfg = new AoqClientEngine.AoqConnectConfig();
cfg.token = obj.optString("aoqTokenForClient", "");
cfg.sid = obj.optString("sid", "");
cfg.certFingerprint = obj.optString("clientRelayCertFingerprint", "");

JSONArray arr = obj.optJSONArray("clientRelayEndpoints");
if (arr != null) {
    for (int i = 0; i < arr.length(); i++) {
        JSONObject o = arr.optJSONObject(i);
        AoqClientEngine.AoqRelayEndpoint ep = new AoqClientEngine.AoqRelayEndpoint();
        // route_index 缺省时按数组下标兜底
        ep.routeIndex = o.has("route_index") ? o.optInt("route_index", i) : i;
        ep.endpoint = o.optString("endpoint", "");
        ep.port = o.optInt("port", 0);
        cfg.relayEndpoints.add(ep);
    }
}

JSONObject ext = obj.optJSONObject("extraInfo");
cfg.workspaceIdHash = ext != null ? ext.optString("workspaceIdHash", "") : "";

AoqClientEngine.AoqTrackParam audio = new AoqClientEngine.AoqTrackParam();
audio.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeAudio;
AoqClientEngine.AoqTrackParam data = new AoqClientEngine.AoqTrackParam();
data.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeData;
cfg.publishTracks.add(audio);
cfg.publishTracks.add(data);
cfg.subscribeTracks.add(audio);
cfg.subscribeTracks.add(data);

engine.connect(cfg);
const obj = JSON.parse(responseText) as Record<string, Object | undefined>;
const cfg: AoqConnectConfig = {
    token: String(obj['aoqTokenForClient'] ?? ''),
    sid: String(obj['sid'] ?? ''),
    certFingerprint: String(obj['clientRelayCertFingerprint'] ?? ''),
    // route_index 缺省时按数组下标兜底
    relayEndpoints: (obj['clientRelayEndpoints'] as Array<any>).map((item, index) => ({
        routeIndex: Number(item['route_index'] ?? index),
        endpoint: String(item['endpoint'] ?? ''),
        port: Number(item['port'] ?? 0)
    })),
    workspaceIdHash: String((obj['extraInfo'] as any)?.['workspaceIdHash'] ?? ''),
    publishTracks: [
        { trackType: AoqTrackType.AoqTrackTypeAudio },
        { trackType: AoqTrackType.AoqTrackTypeData }
    ],
    subscribeTracks: [
        { trackType: AoqTrackType.AoqTrackTypeAudio },
        { trackType: AoqTrackType.AoqTrackTypeData }
    ]
};
engine.connect(cfg);

整體流程

AOQ 接入時序圖
  1. 用戶端透過業務 AppServer 獲取連接憑證。
  2. 建立 SDK 引擎並註冊回調。
  3. 配置媒體和 Data 軌道,關閉上行媒體發送。
  4. 建立 AOQ 連接,等待連接成功。
  5. 按模型協議完成配置,收到確認後開啓所需媒體發送。
  6. 完成交互後斷開連接並釋放資源。

說明

  • 音訊媒體資料由 AOQ SDK 接管,負責採集、處理、發送、接收和播放;Data 資料需要呼叫方遵循目標模型的事件定義進行發送和接收。

  • 連接成功表示與模型的傳輸通道已建立,用戶端應在模型初始化完成後再開啓所需的上行媒體。對於本頁示例型號 qwen-audio-3.1-realtime-plus,發送 session.update 後需等待 session.updated,再開啓媒體發送。

1. 獲取連接憑證

用戶端向業務 AppServer 請求憑證。AppServer 使用本模型的 Realtime 建連地址,並攜帶 API Key 和 x-dashscope-rtc-transport: moq 請求網關。完整地址、請求和欄位說明見 Token 鑒權。

將響應映射到 AoqConnectConfig:

網關響應SDK 配置
aoqTokenForClienttoken
sidsid
clientRelayCertFingerprintcertFingerprint
clientRelayEndpointsrelayEndpoints,按結構轉換各接入點
extraInfo 中的 workspaceIdHashworkspaceIdHash

新建連接時獲取新的連接憑證。同一連接內能否復用會話或啓動下一輪任務,由目標模型協議決定。

2. 初始化 SDK 並註冊回調

建立引擎並註冊連接狀態、Data 消息和錯誤回調。以 iOS Swift 為例:

let createConfig = AoqCreateConfig()
createConfig.workDir = workDir
createConfig.enableDumpAudio = false
engine = AoqClientEngine.createEngine(createConfig, delegate: self)

實現 AoqEngineDelegate,在 onConnectionStatusChange 中維護連接狀態,在 onDataMsg 中解析目標模型事件,在 onError 中處理 SDK 錯誤。模型返回的錯誤事件也需要在 Data 消息處理邏輯中單獨處理。SDK 介面及錯誤說明請參見 各平台 SDK和功能參考。

3. 配置 SDK

選擇媒體方向

以下“推”和“拉”均以用戶端為視角。按業務實際使用的輸入、輸出模態配置,不需要的方向不添加媒體軌道。

方向配置內容典型用途
推音訊發佈 Audio 軌,設置音訊編碼器,配置內置或外部採集語音對話
拉音訊訂閱 Audio 軌,設置音訊解碼器,配置播放器或外部播放語音回覆

Data 軌獨立於音訊方向:發佈 Data 軌用於發送模型事件,訂閱 Data 軌用於接收回覆。純文本輸入或輸出也需要 Data 軌。

本模型的媒體方向

下表列出本模型的媒體方向。模型範圍見適用範圍,其他接入方式參見Qwen-Audio-Realtime。

模型/應用推音訊拉音訊推視訊拉視訊
Qwen-Audio-Realtime語音對話時開啓需要語音回覆時開啓不支援開啓不支援開啓

配置媒體參數和軌道

音訊上行和下行應分別配置:上行使用 setAudioEncoderConfig,下行使用 setAudioDecoderConfig。這些參數用於網絡傳輸,網關會將音訊轉換為模型所需的格式。傳輸編碼配置與模型事件中的音訊格式參數應分別按 SDK 和目標模型的要求設置。

按方向啓動 startAudioCapture 或 startAudioPlayer。自定義輸入輸出見下文高階能力。

publishTracks 表示用戶端發送的軌道,subscribeTracks 表示用戶端接收的軌道:

場景publishTrackssubscribeTracks
語音對話Audio、DataAudio、Data

在建連前關閉上行媒體發送,避免模型尚未就緒時收到輸入:

engine.enableSendMediaStream(.audio, enable: false)

採集、發佈軌道和允許發送是不同的操作。關閉發送不等於停止本地採集,也不影響 Data 軌事件收發。未添加的軌道不會因開啓發送而自動建立。

4. 建立連接

將憑證與軌道配置填入 AoqConnectConfig,呼叫:

engine.connect(connectConfig)

等待 onConnectionStatusChange 返回 .connected,再進入模型初始化流程。connect 呼叫返回不等於連接成功。

5. 按模型協議交互並收發媒體

發送和解析模型事件

用戶端透過 Data 軌發送事件。以下為 iOS Swift 代碼片段,其他介面詳見 iOS SDK 參考:

// eventJSON 由目标模型的客户端事件协议构造。
let msg = AoqDataMsg()
msg.data = eventJSON.data(using: .utf8)!
engine.send(msg)

在 onDataMsg 中解析回覆。本模型透過 type 欄位標識事件類型。完整欄位、參數及結束條件應遵循目標模型文檔。

就緒後開啓所需媒體

滿足當前模型、當前會話或任務的就緒條件後,僅開啓已配置的上行方向。例如,需要語音輸入時呼叫:

engine.enableSendMediaStream(.audio, enable: true)

音訊透過 Audio 軌傳輸;模型事件和文本透過 Data 軌傳輸。不要使用 input_audio_buffer.append 重復發送音訊。下行音訊由已配置的播放器或外部播放邏輯處理。

6. 結束交互並釋放資源

不再使用連接時,由用戶端業務層呼叫AOQ SDK 的斷開連接和釋放資源介面:

engine.disconnect()
AoqClientEngine.destroy()

異常斷開後清理業務層就緒狀態,按連接狀態管理處理後續連接;重新建連後按模型協議重新初始化。

Data 通道發送和接收事件

用戶端透過 AOQ SDK 的 Data 軌發送和接收模型事件。連接時需要發佈和訂閱 Data 軌;發送時將模型事件序列化後放入 AoqDataMsg,並呼叫所用平台的 Data 發送介面;接收時在 onDataMsg 回調中解析消息。介面詳見各平台 SDK。

發送事件的名稱、欄位、參數和呼叫時機遵循目標模型的用戶端事件定義;收到消息後的解析方式、狀態變更、結果和錯誤處理遵循該模型的服務端事件定義。初始化事件根據模型要求按需發送,後續文本和控制事件按照業務需要發送。

模型/應用用戶端事件定義(發送)服務端事件定義(接收)
Qwen-Audio-Realtime用戶端事件服務端事件

模型事件的發送與接收還應遵循以下規則:

  • 使用事件的 type 欄位識別模型事件,關聯標識按本模型事件參考處理。

  • 模型要求的初始化確認、輸入提交、響應取消和任務結束等操作,均在 Data 通道中按對應協議處理;它們屬於模型交互語義,與斷開傳輸連接是不同操作。

  • 結束前按本模型事件說明完成輸入提交和結果接收;需要完整播放時,處理完本地待播音訊再釋放連接。

  • 音訊資料透過媒體軌道傳輸。引用模型事件文檔時,媒體封裝和可用交互模式仍遵循本文的接入方式,不直接套用 WebSocket 的媒體發送方式。

高階能力

能力使用場景文檔
控制音訊發送等待模型就緒、暫停音訊上行媒體流發送管理
音訊設備與處理編解碼、揚聲器、文件混音、音訊幀回調音訊常用功能
外部音訊輸入使用業務側音訊源自定義音訊採集
外部音訊輸出由業務側處理或播放輸出音訊自定義音訊播放

AOQ SDK 的通用視訊介面參見視訊常用功能(SDK 通用)和自定義視訊輸入(SDK 通用);本模型不支援視訊輸入或輸出。

媒體發送控制只控制媒體傳輸。模型響應取消、輪次提交等行為仍需使用目標模型的事件協議。

會話配置示例

說明以下示例適用於 qwen-audio-3.1-realtime-plus。音訊透過媒體軌道傳輸,不使用 WebSocket 的媒體發送事件。

{
  "type": "session.update",
  "session": {
    "voice": "longanqian_v3.1"
  }
}

AOQ SDK 下載

以下版本更新說明描述 AOQ SDK 的通用能力,本模型的媒體支援範圍見上方本模型的媒體方向。

版本平台下載更新日期更新說明

v1.4.0

Android

AoqClientSdk-release.aar

libPluginOpus.zip

2026-10-27

  1. 支援從外部輸入 H.264 視訊。
  2. 優化性能。
  3. 修復已知的穩定性問題。

iOS

AoqClientSdk.framework.zip

AoqScreenShare.framework.zip

PluginOpus.framework.zip

HarmonyOS

AoqClientSdk.har

libPluginOpus.zip

Windows

AoqClientSdk-windows-x64.zip

macOS

AoqClientSdk.framework.zip

PluginOpus.framework.zip

Electron

aoq-electron-sdk-1.4.0-59463182.tgz

也可以透過 npm 安裝:

npm install aoq-electron-sdk@1.4.0-59463182

Linux

x86_64: AoqClientSdk.zip

arm64: AoqClientSdk.zip

v1.3.0Android2026-09-18
  1. 新增屏幕共享能力。

  2. 廢棄 bitcode。

  3. 支援遠程加載 .so 庫。

  4. 支援從外部設置編碼幀最大值。

  5. 將預設編解碼器調整為 Opus。

  6. 優化性能。

  7. 修復已知的穩定性問題。

iOS
HarmonyOS
WindowsAoqClientSdk-windows-x64.zip
macOS
Electron
也可以透過 npm 安裝:npm install aoq-electron-sdk@1.3.0-58586345
Linux
v1.2.2iOSAoqClientSdk.framework.zip2026-09-09
  1. 修復 iOS 通話被系統或第三方語音通話打斷後,在中斷結束時無法恢復通話的問題。

  2. 優化 iOS 通話起始階段的回聲抑制效果。

v1.2.0Android 2026-08-17
  1. 新增macOS平台支援

  2. 新增Windows平台支援

  3. 新增Electron平台支援

  4. Linux平台同時支援Python和C++介面

  5. 新增音量檢測功能

  6. 優化性能

  7. 修复已知的稳定性问题

iOS
HarmonyOS
Windows
macOS
Electron
也可以透過npm安裝:npm install aoq-electron-sdk@1.2.0-57407598
Linux
v1.1.0Android 2026-07-31
  1. 支援ASR模型

  2. 支援TTS模型

  3. 支援多模態交互套件

  4. 新增支援Linux平台

  5. 優化性能

  6. 解決已知的穩定性問題

iOS
HarmonyOS
LinuxAoqClientSdk.zip
v1.0.1Android 2026-07-09
  1. 支援AOQ協議接入模型/應用

  2. 支援音訊與視訊編解碼參數

  3. 支援音訊與視訊設備採集及播放

  4. 支援自定義外部輸入音訊採集

  5. 支援自定義外部輸入視訊採集

  6. 支援自定義外部輸入視訊編碼

  7. 支援控制媒體流的發送

iOS
HarmonyOS

重要AOQ使用音訊插件的方式加載Opus編解碼器,如果需要Opus編解碼時需要下載Opus插件並加載到工程內。

事件參考

場景教程