CosyVoice 用戶端事件參考,介紹 run-task、continue-task、finish-task 的欄位、傳送順序及對應伺服器事件。
事件互動流程
- 傳送 run-task 啟動並設定任務,等待 task-started。
- 收到
task-started後,透過 continue-task 傳送文字,同時接收 result-generated 和合成音訊。 - 文字全部傳送完畢後,傳送 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可選音頻編碼格式。
取值範圍:
pcmwavmp3(預設)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可選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": {}
}
}