本文介紹語音合成CosyVoice Python SDK的參數和介面細節。
本文檔僅適用於“中國大陸(北京)”地區。如需使用模型,需使用“中國大陸(北京)”地區的API Key。
使用者指南:關於模型介紹和選型建議請參見即時語音合成-CosyVoice/Sambert。
前提條件
已開通服務並擷取與配置 API Key。請配置API Key到環境變數(準備下線,併入配置 API Key),而非寫入程式碼在代碼中,防範因代碼泄露導致的安全風險。
說明當您需要為第三方應用或使用者提供臨時存取權限,或者希望嚴格控制敏感性資料訪問、刪除等高風險操作時,建議使用臨時鑒權Token。
與長期有效 API Key 相比,臨時鑒權 Token 具備時效性短(60秒)、安全性高的特點,適用於臨時調用情境,能有效降低API Key泄露的風險。
使用方式:在代碼中,將原本用於鑒權的 API Key 替換為擷取到的臨時鑒權 Token 即可。
模型與價格
模型名稱 | 單價 |
cosyvoice-v3-plus | $0.286706/萬字元 |
cosyvoice-v3-flash | $0.14335/萬字元 |
cosyvoice-v2 | $0.286706/萬字元 |
語音合成文本限制與格式規範
文本長度限制
字元計算規則
漢字(包括簡/繁體漢字、日文漢字和韓文漢字)按2個字元計算,其他所有字元(如標點符號、字母、數字、日韓文假名/諺文等)均按 1個字元計算
計算文本長度時,不包含SSML 標籤內容
樣本:
"你好"→ 2(你)+2(好)=4字元"中A文123"→ 2(中)+1(A)+2(文)+1(1)+1(2)+1(3)=8字元"中文。"→ 2(中)+2(文)+1(。)=5字元"中 文。"→ 2(中)+1(空格)+2(文)+1(。)=6字元"<speak>你好</speak>"→ 2(你)+2(好)=4字元
編碼格式
需採用UTF-8編碼。
數學運算式支援說明
當前數學運算式解析功能僅適用於cosyvoice-v2、cosyvoice-v3-flash和cosyvoice-v3-plus模型,支援識別中小學常見的數學運算式,包括但不限於基礎運算、代數、幾何等內容。
詳情請參見LaTeX 方程式轉語音。
SSML標記語言支援說明
當前SSML(Speech Synthesis Markup Language,語音合成標記語言)功能僅cosyvoice-v3-plus、cosyvoice-v3-flash和cosyvoice-v2模型的部分音色可用,使用時需滿足以下條件:
使用DashScope SDK 1.23.4 或更高版本
僅支援同步調用和非同步呼叫(即SpeechSynthesizer類的
call方法),不支援流式調用(即SpeechSynthesizer類的streaming_call方法)使用方法與普通語音合成一致:將包含SSML的文本傳入SpeechSynthesizer類的
call方法即可
快速開始
SpeechSynthesizer類提供了語音合成的關鍵介面,支援以下幾種調用方式:
同步調用:阻塞式,一次性發送完整文本,直接返回完整音頻。適合短文本語音合成情境。
非同步呼叫:非阻塞式,一次性發送完整文本,通過回呼函數接收音頻資料(可能分區)。適用於對即時性要求高的短文本語音合成情境。
流式調用:非阻塞式,可分多次發送文本片段,通過回呼函數即時接收增量合成的音頻流。適合即時性要求高的長文本語音合成情境。
同步調用
提交單個語音合成任務,無需調用回呼函數,進行語音合成(無流式輸出中間結果),最終一次性擷取完整結果。
執行個體化SpeechSynthesizer類綁定請求參數,調用call方法進行合成並擷取二進位音頻資料。
發送的文本長度不得超過2000字元(詳情請參見SpeechSynthesizer類的call方法)。
每次調用call方法前,需要重新初始化SpeechSynthesizer執行個體。
非同步呼叫
提交單個語音合成任務,通過回調的方式流式輸出中間結果,合成結果通過ResultCallback中的回呼函數流式擷取。
執行個體化SpeechSynthesizer類綁定請求參數和回調介面(ResultCallback),調用call方法進行合成並通過回調介面(ResultCallback)的on_data方法即時擷取合成結果。
發送的文本長度不得超過2000字元(詳情請參見SpeechSynthesizer類的call方法)。
每次調用call方法前,需要重新初始化SpeechSynthesizer執行個體。
流式調用
在同一個語音合成任務中分多次提交文本,並通過回調的方式即時擷取合成結果。
流式輸入時可多次調用
streaming_call按順序提交文本片段。服務端接收文本片段後自動進行分句:完整語句立即合成
不完整語句緩衝至完整後合成
調用
streaming_complete時,服務端會強制合成所有已接收但未處理的文本片段(包括未完成的句子)。發送文本片段的間隔不得超過23秒,否則觸發“request timeout after 23 seconds”異常。
若無待發送文本,需及時調用
streaming_complete結束任務。服務端強制設定23秒逾時機制,用戶端無法修改該配置。
執行個體化SpeechSynthesizer類
串流
多次調用SpeechSynthesizer類的
streaming_call方法分區提交待合成文本,將待合成文本分段發送至服務端。在發送文本的過程中,服務端會通過回調介面(ResultCallback)的
on_data方法,將合成結果即時返回給用戶端。每次調用
streaming_call方法發送的文本片段(即text)長度不得超過2000字元,累計發送的文本總長度不得超過20萬字元。結束處理
調用SpeechSynthesizer類的
streaming_complete方法結束語音合成。該方法會阻塞當前線程,直到回調介面(ResultCallback)的
on_complete或者on_error回調觸發後才會釋放線程阻塞。請務必確保調用該方法,否則可能會導致結尾部分的文本無法成功轉換為語音。
請求參數
請求參數通過SpeechSynthesizer類的構造方法進行設定。
參數 | 類型 | 預設值 | 是否必須 | 說明 |
model | str | - | 是 | 指定模型。 不同版本的模型編碼方式一致,但使用時須確保模型( |
voice | str | - | 是 | 指定語音合成所使用的音色。 支援預設音色和專屬音色:
⚠️ 使用聲音複刻系列模型合成語音時,僅能使用該模型複刻產生的專屬音色,不能使用預設音色。 ⚠️ 使用專屬音色合成語音時,語音合成模型( |
format | enum | mp3 | 否 | 指定音頻編碼格式及採樣率。 若未指定 說明 預設採樣率代表當前音色的最佳採樣率,預設條件下預設按照該採樣率輸出,同時支援降採樣或升採樣。 可指定的音頻編碼格式及採樣率如下:
|
volume | int | 50 | 否 | 合成音訊音量,取值範圍:0~100。 重要 該欄位在不同版本的DashScope SDK中有所不同:
|
speech_rate | float | 1.0 | 否 | 合成音訊語速,取值範圍:0.5~2。
|
pitch_rate | float | 1.0 | 否 | 合成音訊語調,取值範圍:0.5~2。 |
bit_rate | int | 32 | 否 | 指定音訊碼率,取值範圍:6~510kbps。 碼率越大,音質越好,音頻檔案體積越大。 僅在音頻格式( 說明
|
word_timestamp_enabled | bool | False | 否 | 是否開啟字層級時間戳記,預設關閉。 僅cosyvoice-v2支援該功能。 時間戳記結果僅能通過回調介面擷取 說明
|
seed | int | 0 | 否 | 產生時使用的隨機數種子,使合成的效果產生變化。預設值0。取值範圍:0~65535。 |
language_hints | list[str] | - | 否 | 提供語言提示,僅cosyvoice-v3-flash、cosyvoice-v3-plus支援該功能。 在語音合成中有如下作用:
若設定的語言提示與常值內容明顯不符(如為中文文本設定 注意:此參數為數組,但目前的版本僅處理第一個元素,因此建議只傳入一個值。 |
instruction | str | - | 否 | 設定提示詞。僅cosyvoice-v3-flash、cosyvoice-v3-plus支援該功能。 在語音合成中有如下作用:
|
enable_aigc_tag | bool | False | 否 | 是否在產生的音頻中添加AIGC隱性標識。設定為true時,會將隱性標識嵌入到支援格式(wav/mp3/opus)的音頻中。 僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。 說明
|
aigc_propagator | str | 阿里雲UID | 否 | 設定AIGC隱性標識中的 僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。 說明
|
aigc_propagate_id | str | 本次語音合成請求Request ID | 否 | 設定AIGC隱性標識中的 僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。 說明
|
callback | ResultCallback | - | 否 |
關鍵介面
SpeechSynthesizer類
SpeechSynthesizer通過“from dashscope.audio.tts_v2 import *”方式引入,提供語音合成的關鍵介面。
方法 | 參數 | 傳回值 | 描述 |
|
| 沒有指定 | 將整段文本(無論是純文字還是包含SSML的文本)轉換為語音。 在建立
重要 每次調用 |
|
| 無 | 流式發送待合成文本(不支援包含SSML的文本)。 您可以多次調用該介面,將待合成文本分多次發送給服務端。合成結果通過回調介面(ResultCallback)的 使用方法請參見流式調用。 |
|
| 無 | 結束流式語音合成。 該方法阻塞當前線程N毫秒(具體時間長度由 預設情況下,如果等待時間超過10分鐘,則停止等待。 使用方法請參見流式調用。 重要 在流式調用時,請務必確保調用該方法,否則可能會出現合成語音缺失的問題。 |
| 無 | 上一個任務的request_id | 擷取上一個任務的request_id。 |
| 無 | 首包延遲 | 擷取首包延遲(一般在500ms左右)。 首包延遲是開始發送文本和接收第一個音頻包之間的時間,單位為毫秒。在任務完成後使用。 首次發送文本時需建立 WebSocket 串連,因此首包延遲會包含串連建立的耗時。 |
| 無 | 最後一次報文 | 擷取最後一次報文(為JSON格式的資料),可以用於擷取task-failed報錯。 |
回調介面(ResultCallback)
非同步呼叫或流式調用時,服務端會通過回調的方式,將關鍵流程資訊和資料返回給用戶端。您需要實現回調方法,處理服務端返回的資訊或者資料。
通過“from dashscope.audio.tts_v2 import *”方式引入。
方法 | 參數 | 傳回值 | 描述 |
| 無 | 無 | 當和服務端建立串連完成後,該方法立刻被回調。 |
|
| 無 | 當服務有回複時會被回調。 |
| 無 | 無 | 當所有合成資料全部返回(語音合成完成)後被回調。 |
|
| 無 | 發生異常時該方法被回調。 |
|
| 無 | 當伺服器有合成音頻返回時被回調。 您可以將二進位音頻資料合成為一個完整的音頻檔案後使用播放器播放,也可以通過支援流式播放的播放器即時播放。 重要
|
| 無 | 無 | 當服務已經關閉串連後被回調。 |
響應結果
伺服器返回二進位音頻資料:
同步調用:對SpeechSynthesizer類的
call方法返回的二進位音頻資料進行處理。非同步呼叫或流式調用:對回調介面(ResultCallback)的
on_data方法的參數(bytes類型資料)進行處理。
錯誤碼
如遇報錯問題,請參見錯誤資訊進行排查。
更多樣本
更多樣本,請參見GitHub。
常見問題
功能特性/計量計費/限流
Q:當遇到發音不準的情況時,有什麼解決方案可以嘗試?
通過SSML可以對語音合成效果進行個人化定製。
Q:語音合成是按文本字元數計費的,要如何查看或擷取每次合成的文本長度?
根據是否開啟日誌,有不同的擷取方式:
未開啟日誌
同步調用:需要按照字元計算規則自行計算。
其他調用方式:通過回調介面(ResultCallback)
on_event方法的message參數擷取。message為JSON字串,解析可擷取本次請求中計費的有效字元數(characters參數)。請以收到的最後一個message為準。
開啟日誌
在控制台會列印如下日誌,
characters即為本次請求中計費的有效字元數。請以列印的最後一個日誌為準。2025-08-27 11:02:09,429 - dashscope - speech_synthesizer.py - on_message - 454 - DEBUG - <<<recv {"header":{"task_id":"62ebb7d6cb0a4080868f0edb######","event":"result-generated","attributes":{}},"payload":{"output":{"sentence":{"words":[]}},"usage":{"characters":15}}}
故障排查
如遇代碼報錯問題,請根據錯誤碼中的資訊進行排查。
Q:如何擷取Request ID?
通過以下兩種方式可以擷取:
在回調介面(ResultCallback)的
on_event方法中對JSON字串message進行解析。調用SpeechSynthesizer的
get_last_request_id方法。
Q:使用SSML功能失敗是什麼原因?
請按以下步驟排查:
確保當前音色支援SSML功能(聲音複刻音色不支援SSML)
確保
model參數值為cosyvoice-v2確保使用正確的介面:只有SpeechSynthesizer類的
call方法支援SSML確保待合成文本為純文字格式且符合格式要求,詳情請參見SSML標記語言介紹
Q:為什麼音頻無法播放?
請根據以下情境逐一排查:
音頻儲存為完整檔案(如xx.mp3)的情況
音頻格式一致性:確保請求參數中設定的音頻格式與檔案尾碼一致。例如,如果請求參數設定的音頻格式為wav,但檔案尾碼為mp3,可能會導致播放失敗。
播放器相容性:確認使用的播放器是否支援該音頻檔案的格式和採樣率。例如,某些播放器可能不支援高採樣率或特定編碼的音頻檔案。
流式播放音訊情況
將音頻流儲存為完整檔案,嘗試使用播放器播放。如果檔案無法播放,請參考情境 1 的排查方法。
如果檔案可以正常播放,則問題可能出在流式播放的實現上。請確認使用的播放器是否支援流式播放。
常見的支援流式播放的工具和庫包括:ffmpeg、pyaudio (Python)、AudioFormat (Java)、MediaSource (Javascript)等。
Q:為什麼音頻播放卡頓?
請根據以下情境逐一排查:
檢查文本發送速度: 確保發送文本的間隔合理,避免前一句音頻播放完畢後,下一句文本未能及時發送。
檢查回呼函數效能:
檢查回呼函數中是否存在過多商務邏輯,導致阻塞。
回呼函數運行在 WebSocket 線程中,若被阻塞,可能會影響 WebSocket 接收網路資料包,進而導致音頻接收卡頓。
建議將音頻資料寫入一個獨立的音頻緩衝區(audio buffer),然後在其他線程中讀取並處理,避免阻塞 WebSocket 線程。
檢查網路穩定性: 確保網路連接穩定,避免因網路波動導致音頻傳輸中斷或延遲。
Q:語音合成慢(合成時間長)是什麼原因?
請按以下步驟排查:
檢查輸入間隔
如果是流式語音合成,請確認文字發送間隔是否過長(如上段發出後延遲數秒才發送下段),過久間隔會導致合成總時間長度增加。
分析效能指標
首包延遲:正常500ms左右。
RTF(RTF = 合成總耗時/音頻時間長度):正常小於1.0。
Q:合成的語音發音錯誤如何處理?
若當前使用的模型為cosyvoice-v1,推薦使用cosyvoice-v2,v2效果更好且支援SSML。
若當前使用的模型為cosyvoice-v2,請使用SSML的<phoneme>標籤指定正確的發音。
Q:為什麼沒有返回語音?為什麼結尾部分的文本沒能成功轉換成語音?(合成語音缺失)
請檢查是否遺漏了調用SpeechSynthesizer類的streaming_complete方法。在語音合成過程中,服務端會在緩衝足夠文本後才開始合成。如果未調用streaming_complete方法,可能會導致緩衝中的結尾部分文本未能被合成為語音。
Q:SSL認證校正失敗如何處理?
安裝系統根憑證
sudo yum install -y ca-certificates sudo update-ca-trust enable代碼中添加如下內容
import os os.environ["SSL_CERT_FILE"] = "/etc/ssl/certs/ca-bundle.crt"
Q:Mac環境下出現“SSL: CERTIFICATE_VERIFY_FAILED”異常是什麼原因?(websocket closed due to [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1000))
在串連 WebSocket 時,可能會遇到 OpenSSL 驗證認證失敗的問題,提示找不到認證。這通常是由於 Python 環境的認證配置不正確導致的。可以通過以下步驟手動定位並修複認證問題:
匯出系統認證並設定環境變數 執行以下命令,將 macOS 系統中的所有認證匯出到一個檔案,並將其設定為 Python 和相關庫的預設憑證路徑:
security find-certificate -a -p > ~/all_mac_certs.pem export SSL_CERT_FILE=~/all_mac_certs.pem export REQUESTS_CA_BUNDLE=~/all_mac_certs.pem建立符號連結以修複 Python 的 OpenSSL 配置 如果 Python 的 OpenSSL 配置缺失認證,可以通過以下命令手動建立符號連結。請確保替換命令中的路徑為本地 Python 版本的實際安裝目錄:
# 3.9是樣本版本號碼,請根據您本地安裝的 Python 版本調整路徑 ln -s /etc/ssl/* /Library/Frameworks/Python.framework/Versions/3.9/etc/openssl重新啟動終端並清除緩衝 完成上述操作後,請關閉並重新開啟終端,以確保環境變數生效。清除可能的緩衝後重試串連 WebSocket。
通過以上步驟,可以解決因認證配置錯誤導致的串連問題。如果問題仍未解決,請檢查目標伺服器的認證配置是否正確。
Q:運行代碼提示“AttributeError: module 'websocket' has no attribute 'WebSocketApp'. Did you mean: 'WebSocket'?”是什麼原因?
原因是沒有安裝websocket-client或websocket-client版本不匹配,請依次執行以下命令:
pip uninstall websocket-client
pip uninstall websocket
pip install websocket-client許可權與認證
Q:我希望我的 API Key 僅用於 CosyVoice 語音合成服務,而不被百鍊其他模型使用(許可權隔離),我該如何做?
可以通過建立業務空間並只授權特定模型來限制API Key的使用範圍。詳情請參見業務空間管理。
更多問題
請參見GitHub QA。