全部產品
Search
文件中心

Alibaba Cloud Model Studio:CosyVoice AOQ 接入

更新時間:Nov 09, 2026

介紹透過 AOQ 接入 CosyVoice 的鑒權、媒體配置、建連和任務事件處理流程。

透過 AOQ 接入 CosyVoice 時,用戶端透過 Data 軌提交文本和任務事件,透過 Audio 軌接收合成語音。

準備工作

  • 選擇支援 AOQ 的型號。具體支援範圍參見模型與協議支援範圍。
  • 在業務 AppServer 配置與呼叫地域和業務空間匹配的 API Key。
  • 從SDK 下載導入對應平台的 AOQ SDK。下文以 Android Java 和 Opus 傳輸為例,請同時導入 Opus 插件。純文本合成無需申請麥克風或攝像頭權限。

1. 獲取連接憑證

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

在 AppServer 設置環境變量 DASHSCOPE_API_KEY,用所選地域及業務空間的接入域名替換 {endpoint}。CosyVoice 使用 Inference 建連路徑,以下以 cosyvoice-v3-plus 為例。

curl -X POST \
  "https://{endpoint}/api/v1/webrtc/inference?model=cosyvoice-v3-plus" \
  -H "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "x-dashscope-rtc-transport: moq" \
  -d '{}'

若使用 Token Plan,接入域名中的 WorkspaceId 固定為 token-plan。請求體中的 clientIp 可選,填寫用戶端真實公網 IP,供網關選擇 Relay 接入點。未填寫時,網關使用請求來源 IP。

API Key 僅保存在 AppServer。AppServer 將下表中的連接參數返回用戶端,響應中的 sidExpiresInSecs 表示會話有效期,單位為秒。

網關響應欄位AoqConnectConfig 欄位
aoqTokenForClienttoken
sidsid
clientRelayCertFingerprintcertFingerprint
clientRelayEndpointsrelayEndpoints,逐項轉換 endpoint、port 和 route_index
extraInfo.workspaceIdHashworkspaceIdHash

2. 初始化 SDK 並建連

用 AoqCreateConfig 設置 SDK 工作目錄,呼叫 AoqClientEngine.createEngine 建立引擎並註冊回調。在 onConnectionStatusChange 中處理連接狀態,在 onDataMsg 中解析模型事件,在 onError 中處理 SDK 錯誤。Android SDK提供引擎初始化和連接欄位的完整介面說明。

將 AppServer 返回的憑證填入 connectConfig 後,發佈 Data 軌,訂閱 Audio 和 Data 軌。下例設置 24 kHz 單聲道 Opus 解碼並啓動播放器。模型的輸出格式由任務事件指定,SDK 解碼配置用於媒體軌傳輸。

AoqClientEngine.AoqAudioCodecConfig codec = new AoqClientEngine.AoqAudioCodecConfig();
codec.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeAudio;
codec.codecType = AoqClientEngine.AoqEncoderType.AoqEncoderTypeAudioOpus;
codec.sampleRate = 24000;
codec.channel = 1;
engine.setAudioDecoderConfig(codec);

AoqClientEngine.AoqTrackParam audio = new AoqClientEngine.AoqTrackParam();
audio.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeAudio;
connectConfig.subscribeTracks.add(audio);
AoqClientEngine.AoqTrackParam publishData = new AoqClientEngine.AoqTrackParam();
publishData.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeData;
connectConfig.publishTracks.add(publishData);
AoqClientEngine.AoqTrackParam subscribeData = new AoqClientEngine.AoqTrackParam();
subscribeData.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeData;
connectConfig.subscribeTracks.add(subscribeData);

AoqClientEngine.AoqAudioPlaybackConfig playback = new AoqClientEngine.AoqAudioPlaybackConfig();
playback.channel = 1;
playback.isDefaultSpeaker = true;
engine.startAudioPlayer(playback);
engine.connect(connectConfig);

等待 onConnectionStatusChange 返回 AoqConnectionStatusConnected 後再啓動任務。連接異常時清理本地任務狀態,重新建連需要獲取新的連接憑證。

3. 啓動合成任務並處理事件

將以下 JSON 序列化為 UTF-8,寫入 AoqDataMsg.data,再用 sendDataMsg 透過 Data 軌發送。每個任務生成新的 task_id,本輪的所有事件使用同一個值。使用與所選型號匹配的音色。

{
  "header": {
    "action": "run-task",
    "task_id": "0706c14c-dc16-4e45-8cb6-9d00686e8e19",
    "streaming": "duplex"
  },
  "payload": {
    "task_group": "audio",
    "task": "tts",
    "function": "SpeechSynthesizer",
    "model": "cosyvoice-v3-plus",
    "parameters": {
      "text_type": "PlainText",
      "voice": "longanyang",
      "format": "pcm",
      "sample_rate": 24000
    },
    "input": {}
  }
}

在 onDataMsg 中讀取 header.event。收到 task-started 後,發送一個或多個 continue-task 提交文本。

{
  "header": {
    "action": "continue-task",
    "task_id": "0706c14c-dc16-4e45-8cb6-9d00686e8e19",
    "streaming": "duplex"
  },
  "payload": {
    "input": {
      "text": "欢迎使用阿里云百炼。"
    }
  }
}

SDK 從 Audio 軌接收並播放語音。result-generated 是 Data 軌上的任務事件,音訊由 Audio 軌傳輸。收到 task-failed 時,讀取 header.error_code 和 header.error_message,並結束本輪任務。

任務參數與事件欄位參見用戶端事件和服務端事件。

4. 結束任務並釋放資源

提交全部文本後發送 finish-task。保持連接,等待服務端合成剩餘文本並返回 task-finished。

{
  "header": {
    "action": "finish-task",
    "task_id": "0706c14c-dc16-4e45-8cb6-9d00686e8e19",
    "streaming": "duplex"
  },
  "payload": {
    "input": {}
  }
}

不再使用連接時,等待已接收的音訊播放結束,依次呼叫 stopAudioPlayer、disconnect 和 AoqClientEngine.destroy 釋放資源。

相關文檔