本文介紹通過DashScope Python SDK進行CosyVoice即時語音合成的類定義、請求參數和範例程式碼。
介面地址
SDK的介面地址需在初始化前設定為下方地址(包含WorkspaceId)。如需切換到其他地區,請修改 dashscope.base_websocket_api_url為對應地區的URL。
- 新加坡
- 華北2(北京)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference調用時請將{WorkspaceId}替換為真實的Workspace ID。SpeechSynthesizer
包路徑:dashscope.audio.tts_v2.SpeechSynthesizer
構造方法
call() - 非流式調用
方法簽名:
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
text | str | 是 | 待合成的完整文本,長度不得超過20000字元。 |
bytes,完整音頻資料。
說明:非流式調用,阻塞等待並一次性返回完整音頻資料。適用於短文本、對即時性無嚴格要求的情境。每次調用前需重新初始化SpeechSynthesizer執行個體。
streaming_call() - 流式調用
方法簽名:
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
text | str | 是 | 當前待合成的文本片段。可多次調用以追加文本,單次不超過20000字元,累計不超過20萬字元。 |
streaming_complete() - 結束流式合成
方法簽名:
streaming_cancel() - 取消流式合成
方法簽名:
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
complete_timeout_millis | int | 否 | 等待服務端返回 task-finished 事件的逾時時間,單位毫秒。預設值:10000。 |
SpeechSynthesizer 執行個體。
get_last_request_id() - 擷取請求ID
方法簽名:
str,最近一次請求的request_id,可用於問題排查和日誌關聯。
get_first_package_delay() - 擷取首包延遲
方法簽名:
float,從發送文本到收到第一塊音頻資料的延遲時間(毫秒)。需在合成完成後調用。
get_response() - 擷取響應訊息
方法簽名:
dict,最近一次合成任務的響應訊息(含 header/payload 鍵)。
構造參數
以下參數通過SpeechSynthesizer構造方法設定,用於控制合成音訊模型、音色、格式和音頻特徵。
| 參數 | 類型 | 是否必須 | 說明 |
|---|---|---|---|
model | str | 是 | 模型名稱。 |
voice | str | 是 | 語音合成所使用的音色。
|
format | enum | 否 | 音頻編碼格式及採樣率。預設值:AudioFormat.MP3_22050HZ_MONO_256KBPS。AudioFormat枚舉類的包路徑:dashscope.audio.tts_v2,支援MP3、WAV、PCM等格式。 |
volume | int | 否 | 音量。預設值:50。取值範圍:[0, 100]。 |
speech_rate | float | 否 | 語速。預設值:1.0。取值範圍:[0.5, 2.0]。 |
pitch_rate | float | 否 | 音調。預設值:1.0。取值範圍:[0.5, 2.0]。 |
bit_rate | int | 否 | 音頻碼率(kbps)。音頻格式為mp3或opus時,支援通過bit_rate參數調整碼率。預設值:32。取值範圍:[6, 510]。bit_rate需要通過additional_params參數進行設定: |
word_timestamp_enabled | bool | 否 | 是否開啟字層級時間戳記。預設值:false。僅在流式輸出模式下可用。支援的音色範圍:cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2模型的複刻音色,以及CosyVoice音色列表中標記為支援的系統音色。其他模型的複刻音色不支援此功能。word_timestamp_enabled需要通過additional_params參數進行設定: |
seed | int | 否 | 產生時使用的隨機數種子,使合成的效果產生變化。在模型版本、文本、音色及其他參數均相同的前提下,使用相同的seed可複現相同的合成結果。預設值0。取值範圍:[0, 65535]。 |
language_hints | list[str] | 否 | 指定語音合成的目標語言,提升合成效果。當數字、縮寫、符號等朗讀方式或者小語種合成效果不符合預期時使用,例如:
取值範圍
|
instruction | str | 否 | 設定指令,用於控制方言、情感或角色等合成效果。使用說明請參見指令控制。 |
enable_aigc_tag | bool | 否 | 是否在產生的音頻中添加AIGC隱性標識。設定為true時,會將隱性標識嵌入到支援格式(wav/mp3/opus)的音頻中。預設值:false。 僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。 enable_aigc_tag、aigc_propagator和aigc_propagate_id需要通過additional_params參數進行設定: |
aigc_propagator | str | 否 | 設定AIGC隱性標識中的 ContentPropagator 欄位,用於標識內容的傳播者。僅在 enable_aigc_tag 為 true 時生效。預設值:阿里雲UID。僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。 additional_params參數進行設定,參見enable_aigc_tag的樣本。 |
aigc_propagate_id | str | 否 | 設定AIGC隱性標識中的 PropagateID 欄位,用於唯一標識一次具體的傳播行為。僅在 enable_aigc_tag 為 true 時生效。預設值:本次語音合成請求Request ID。僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。 additional_params參數進行設定,參見enable_aigc_tag的樣本。 |
hot_fix | dict | 否 | 文本熱修複配置,用於自訂指定詞語的發音或對待合成文本進行替換。 cosyvoice-v2不支援該功能。
|
enable_markdown_filter | bool | 否 | 僅cosyvoice-v3-flash複刻音色支援該功能。
enable_markdown_filter需要通過additional_params參數進行設定: |
callback | ResultCallback | 否 | 回呼函數執行個體,用於非同步接收合成音頻和事件通知。設定此參數時,call()方法以流式模式運行,音頻資料通過on_data回調返回;不設定時,call()以非流式模式運行,直接返回完整音訊bytes資料。 |
ResultCallback
包路徑:dashscope.audio.tts_v2.ResultCallback
on_open() - 串連建立
方法簽名:
on_event() - 接收服務端回複
方法簽名:
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
message | str | 是 | 服務端響應事件(JSON格式),包含header(請求資訊)和payload(輸出資訊)。其中payload.output包含事件類型、原始文本等資訊,詳見on_event訊息中的output欄位。 |
json.loads(message)解析後訪問payload.output擷取詳細資料。
on_complete() - 合成完成
方法簽名:
on_data() - 接收音頻資料
方法簽名:
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
data | bytes | 是 | 當前批次的音頻位元據片段,格式由構造參數format指定。 |
on_error() - 發生錯誤
方法簽名:
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
message | str | 是 | 錯誤描述資訊,包含錯誤碼和詳細原因。 |
on_close() - 串連關閉
方法簽名:
on_event訊息中的output欄位
on_event回調接收的JSON訊息中,payload.output包含合成事件的輸出資訊,可用於跟蹤合成進度和擷取逐句資訊。以下為output欄位的結構說明:
| 欄位 | 類型 | 說明 |
|---|---|---|
type | str | 事件類型。取值為sentence-begin(句子合成開始)、sentence-synthesis(句子合成中)或sentence-end(句子合成結束)。 |
original_text | str | 當前句子的原始文本。在sentence-begin和sentence-end事件中返回。 |
sentence | dict | 句子資訊。包含index(句子序號)和words(詞列表,開啟word_timestamp_enabled時返回時間戳記資訊)。 |
範例程式碼
SDK提供了語音合成的關鍵介面,支援以下幾種調用方式:
- 非流式調用:阻塞式,一次性發送完整文本,直接返回完整音頻。適合短文本語音合成情境。
- 單向流式調用:非阻塞式,一次性發送完整文本,通過回呼函數接收音頻資料(可能分區)。適用於對即時性要求高的短文本語音合成情境。
- 雙向流式調用:非阻塞式,可分多次發送文本片段,通過回呼函數即時接收增量合成的音頻流。適合即時性要求高的長文本語音合成情境。
- 非流式調用
- 單向流式調用
- 雙向流式調用
單次調用發送的文本長度不得超過20000字元,超出限制將返回錯誤。