全部產品
Search
文件中心

Alibaba Cloud Model Studio:CosyVoice用戶端事件

更新時間:Nov 16, 2026

CosyVoice 用戶端事件參考,介紹 run-task、continue-task、finish-task 的欄位、傳送順序及對應伺服器事件。

事件互動流程

  1. 傳送 run-task 啟動並設定任務,等待 task-started。
  2. 收到 task-started 後,透過 continue-task 傳送文字,同時接收 result-generated 和合成音訊。
  3. 文字全部傳送完畢後,傳送 finish-task,繼續接收剩餘結果和音訊,直到收到 task-finished;任務失敗時傳回 task-failed。

result-generated 傳回句子中繼資料,音訊資料透過獨立通道傳輸:WebSocket 使用二進位訊框,AOQ 使用 Audio Track。連線、驗證和音訊傳輸方式請參閱 WebSocket API 或 AOQ 接入。

run-task

建立連線後,用戶端立即傳送 run-task 事件,啟動語音合成任務並設定模型、音色、取樣率等參數。

重要收到 task-started 後才能傳送 continue-task。 run-task 僅用於啟動和設定任務,待合成文字透過 continue-task 傳送。

headerobject必填
actionstring必填

指令類型,固定為 run-task。

task_idstring必填

用戶端產生的任務 ID(UUID 格式),用於關聯後續事件。和後續 continue-task、finish-task 中的 task_id 保持一致。

streamingstring必填

固定為 duplex

payloadobject必填
task_groupstring必填

工作群組,固定為 audio。

taskstring必填

任務類型,固定為 tts。

functionstring必填

功能類型,固定為 SpeechSynthesizer。

modelstring必填

模型名稱。

parametersobject必填

語音合成參數。

text_typestring必填

固定為 PlainText。

voicestring必填

語音合成所使用的音色。

  • 系統音色:參見CosyVoice音色列表
  • 複刻音色:通過音色複刻功能定製
  • 音色設計音色:通過音色設計功能定製
formatstring可選

音頻編碼格式。

取值範圍:

  • pcm
  • wav
  • mp3(預設)
  • opus
sample_rateinteger可選

音頻採樣率(Hz)。

取值範圍:8000, 16000, 22050(預設), 24000, 44100, 48000。

volumeinteger可選

音量。

預設值:50。

取值範圍:[0, 100]。

ratefloat可選

語速。

預設值:1.0。

取值範圍:[0.5, 2.0]。

pitchfloat可選

音調。

預設值:1.0。

取值範圍:[0.5, 2.0]。

bit_rateinteger可選

音頻碼率(kbps)。音頻格式為mp3或opus時,支援通過bit_rate參數調整碼率。

預設值:32。

取值範圍:[6, 510]。

enable_ssmlboolean可選

是否開啟 SSML 功能。

預設值:false。

說明設為 true 後,僅允許發送一次 continue-task 指令。

SSML 的使用限制(支援的模型、音色和介面),請參見使用限制。

word_timestamp_enabledboolean可選

是否開啟字層級時間戳記。

預設值:false。

說明僅在流式輸出模式下可用。支援的音色範圍:cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2模型的複刻音色,以及CosyVoice音色列表中標記為支援的系統音色。其他模型的複刻音色不支援此功能。

seedinteger可選

產生時使用的隨機數種子,使合成的效果產生變化。在模型版本、文本、音色及其他參數均相同的前提下,使用相同的seed可複現相同的合成結果。

預設值0。

取值範圍:[0, 65535]。

language_hintsarray[string]可選

說明

  • 此參數為數組,但目前的版本僅處理第一個元素,因此建議只傳入一個值。
  • 此參數用於指定語音合成的目標語言,該設定與音色複刻時的樣本音訊語種無關。如需設定複刻任務的源語言,請參見音色複刻API參考。

指定語音合成的目標語言,提升合成效果。

當數字、縮寫、符號等朗讀方式或者小語種合成效果不符合預期時使用,例如:

  • 數字朗讀方式不符合預期,“hello, this is 110”讀成“hello, this is one one zero”而非“hello, this is 么么零”
  • 符號朗讀不準確,“@”讀成“艾特”而非“at”
  • 小語種合成效果差,合成不自然

取值範圍

  • zh:中文
  • en:英語
  • fr:法語
  • de:德語
  • ja:日語
  • ko:韓語
  • ru:俄語
  • pt:葡萄牙語
  • th:泰語
  • id:印尼語
  • vi:越南語
  • es:西班牙語
  • it:意大利語
  • ms:馬來西亞語
  • fil:菲律賓語
  • ar:阿拉伯語
instructionstring可選

設定指令,用於控制方言、情感或角色等合成效果。具體使用說明請參見指令控制。

enable_aigc_tagboolean可選

是否在產生的音頻中添加AIGC隱性標識。設定為true時,會將隱性標識嵌入到支援格式(wav/mp3/opus)的音頻中。

預設值:false。

說明僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。

aigc_propagatorstring可選

設定AIGC隱性標識中的 ContentPropagator 欄位,用於標識內容的傳播者。僅在 enable_aigc_tag 為 true 時生效。

預設值:阿里雲UID。

說明僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。

aigc_propagate_idstring可選

設定AIGC隱性標識中的 PropagateID 欄位,用於唯一標識一次具體的傳播行為。僅在 enable_aigc_tag 為 true 時生效。

預設值:本次語音合成請求Request ID。

說明僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。

hot_fixobject可選

文本熱修複配置,用於自訂指定詞語的發音或對待合成文本進行替換。

說明cosyvoice-v2不支援該功能。

參數介紹:

  • pronunciation:自訂發音。指定詞語的拼音標註,用於糾正預設發音不準確的情況。
  • replace:文本替換。在語音合成前將指定詞語替換為目標文本,替換後的文本將作為實際合成內容。

樣本:

以下範例使用拼音標註中文字詞的發音,並替換待合成文字。

{
  "hot_fix": {
    "pronunciation": [
      {
        "天气": "tian1 qi4"
      }
    ],
    "replace": [
      {
        "今天": "金天"
      }
    ]
  }
}
enable_markdown_filterboolean可選

說明僅cosyvoice-v3-flash複刻音色支援該功能。

是否啟用 Markdown 過濾。啟用該功能後,系統在合成語音前自動過濾輸入文本中的 Markdown 標記符號,避免將其朗讀為文字內容。

預設值:false。

取值範圍:

  • true:啟用Markdown過濾
  • false:禁用Markdown過濾
inputobject必填

輸入資料:固定為空白對象 {},待合成文本通過 continue-task 指令發送。

{
  "header": {
    "action": "run-task",
    "task_id": "24a2157d-7eb1-4e8e-958f-5af8acfa8929",
    "streaming": "duplex"
  },
  "payload": {
    "input": {},
    "task_group": "audio",
    "task": "tts",
    "function": "SpeechSynthesizer",
    "model": "cosyvoice-v3-plus",
    "parameters": {
      "text_type": "PlainText",
      "voice": "longanyang",
      "format": "mp3",
      "sample_rate": 22050
    }
  }
}
{
  "header": {
    "task_id": "24a2157d-7eb1-4e8e-958f-5af8acfa8929",
    "task_uuid": "477a77e06a26427eb9745a4f1b1366dc",
    "event": "task-started",
    "attributes": {}
  },
  "payload": {}
}

continue-task

收到 task-started 後,用戶端傳送 continue-task 事件提交待合成文字。文字可一次傳送,也可分段依序傳送。

headerobject必填
actionstring必填

指令類型,固定為 continue-task。

task_idstring必填

任務 ID(UUID 格式),需要和 run-task 中的 task_id 保持一致。

streamingstring必填

固定為 duplex。

payloadobject必填
inputobject必填

包含待合成文本。

textstring必填

待合成文本。單次最多 20000 字元,累計最多 200000 字元。

說明發送間隔不得超過 23 秒,否則連線逾時。

{
  "header": {
    "action": "continue-task",
    "task_id": "24a2157d-7eb1-4e8e-958f-5af8acfa8929",
    "streaming": "duplex"
  },
  "payload": {
    "input": {
      "text": "你好,欢迎使用语音合成。"
    }
  }
}
{
  "header": {
    "task_id": "24a2157d-7eb1-4e8e-958f-5af8acfa8929",
    "event": "result-generated",
    "attributes": {
      "x-dashscope-inner-response-type": "ws"
    }
  },
  "payload": {
    "output": {
      "sentence": {
        "index": 0,
        "words": []
      },
      "type": "sentence-begin",
      "original_text": "你好,欢迎使用语音合成。",
      "normalized_text": "你好,欢迎使用语音合成。"
    }
  }
}

finish-task

所有文字傳送完畢後,用戶端立即傳送 finish-task 事件,通知伺服器文字傳送完畢並請求結束任務。如需取消目前輪次的合成,可在 input 中將 directive 設為 cancel。

重要傳送 finish-task 後,仍須接收剩餘合成結果和音訊,直到收到 task-finished。 取消任務時,伺服器停止輸出後續音訊並傳回 task-finished。

headerobject必填
actionstring必填

指令類型,固定為 finish-task。

task_idstring必填

任務 ID(UUID 格式),需要和 run-task 中的 task_id 保持一致。

streamingstring必填

固定為 duplex

payloadobject必填
inputobject必填

任務輸入。為空白對象 {} 時表示正常結束任務;包含 directive 時可用於取消當前輪次的語音合成任務。

directivestring可選

控制任務結束行為。當前僅支援取值為 cancel,表示取消當前輪次的語音合成任務,服務端會立即返回 task-finished 事件,且不會輸出後續音頻。

取消後,可在當前 WebSocket 串連上重新發起語音合成任務(發送新的 run-task 事件),無需重建立立串連。

正常結束

{
  "header": {
    "action": "finish-task",
    "task_id": "24a2157d-7eb1-4e8e-958f-5af8acfa8929",
    "streaming": "duplex"
  },
  "payload": {
    "input": {}
  }
}
{
  "header": {
    "task_id": "24a2157d-7eb1-4e8e-958f-5af8acfa8929",
    "event": "task-finished",
    "attributes": {
      "x-dashscope-inner-response-type": "ws"
    }
  },
  "payload": {
    "output": {},
    "usage": {
      "characters": 22
    }
  }
}

取消任務

{
  "header": {
    "action": "finish-task",
    "task_id": "701d0875-20f8-4d39-8e50-ee5be2f0e364",
    "streaming": "duplex"
  },
  "payload": {
    "input": {
      "directive": "cancel"
    }
  }
}
{
  "header": {
    "task_id": "701d0875-20f8-4d39-8e50-ee5be2f0e364",
    "event": "task-finished",
    "attributes": {
      "x-dashscope-inner-response-type": "ws"
    }
  },
  "payload": {
    "output": {}
  }
}