聲音複刻Python SDK參考 - Alibaba Cloud Model Studio

本文介紹聲音複刻的Python SDK使用方法。

服務地址

SDK預設使用北京地區的服務端點。如需切換到其他地區，需在初始化前修改 dashscope.base_http_api_url。

國際

服務部署範圍為國際時，模型推理計算資源在全球範圍內動態調度（不含中國內地）；待用資料儲存於您所選的地區。該部署範圍支援的地區：新加坡。

https://dashscope-intl.aliyuncs.com/api/v1

中國內地

服務部署範圍為中國內地時，模型推理計算資源僅限於中國內地；待用資料儲存於您所選的地區。該部署範圍支援的地區：華北2（北京）。

https://dashscope.aliyuncs.com/api/v1

切換到新加坡地區：

import dashscope

# 在代碼開頭設定
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

注意：

不同地區的 API Key 不同，請確保使用對應地區的 API Key
地區配置為全域設定，影響所有 DashScope SDK 的 API 呼叫

VoiceEnrollmentService 類

包路徑：dashscope.audio.tts_v2.VoiceEnrollmentService

功能：管理CosyVoice複刻音色的生命週期（建立、查詢、更新、刪除）。

構造方法

VoiceEnrollmentService()

create_voice() - 建立音色

方法簽名：

def create_voice(self, target_model: str, prefix: str, url: str,
                 language_hints: List[str] = None,
                 max_prompt_audio_length: float = None,
                 enable_preprocess: bool = None) -> str

參數說明：

參數	類型	必填	說明
target_model	str	是	驅動音色的語音合成模型。必須與後續調用語音合成介面時使用的模型一致，否則合成會失敗。
prefix	str	是	音色名稱首碼，僅允許數字和英文字母，不超過10個字元。產生的音色名格式：`{target_model}-{prefix}-{唯一標識}`。
url	str	是	用於複刻音色的音頻檔案URL，要求公網可訪問。
language_hints	List[str]	否	重要僅適用於CosyVoice聲音複刻（model為`voice-enrollment`時），且僅cosyvoice-v3.5-plus、v3.5-flash、v3-plus和v3-flash模型支援。輔助模型識別樣本音訊語種，從而更準確地提取音色特徵，提升複刻效果。若設定的語種與實際音頻語種不符（例如為中文音頻設定 `en`），系統將忽略該設定並自動檢測語種。此參數為數組，但目前的版本僅處理第一個元素。取值範圍（因模型而異）： cosyvoice-v3-plus： zh：中文 en：英文 fr：法語 de：德語 ja：日語 ko：韓語 ru：俄語 cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash： zh：中文 en：英文 fr：法語 de：德語 ja：日語 ko：韓語 ru：俄語 pt：葡萄牙語 th：泰語 id：印尼語 vi：越南語預設值：["zh"]。
max_prompt_audio_length	float	否	重要僅適用於CosyVoice聲音複刻（model為`voice-enrollment`時），且僅cosyvoice-v3.5-plus、v3.5-flash和v3-flash模型支援。音頻預先處理後用於聲音複刻的參考音頻最大時間長度（秒）。取值範圍：[3.0, 30.0]。時間越長效果越好。預設值：10.0。
enable_preprocess	bool	否	重要僅適用於CosyVoice聲音複刻（model為`voice-enrollment`時），且僅cosyvoice-v3.5-plus、v3.5-flash和v3-flash模型支援。是否開啟音頻預先處理（降噪、音頻增強、音量規整）。有背景雜音時建議開啟；安靜環境建議關閉以最大程度還原音色。預設值：false。

傳回值：str，音色ID（voice_id）。

list_voice() - 查詢音色列表

方法簽名：

def list_voice(self, prefix: str = None, page_index: int = 0, page_size: int = 10) -> list

參數說明：

參數	類型	必填	說明
prefix	str	否	按音色名稱首碼篩選。
page_index	int	否	頁碼索引，預設0。
page_size	int	否	每頁條數，預設10。

傳回值：list，音色列表。

query_voice() - 查詢音色詳情

方法簽名：

def query_voice(self, voice_id: str) -> dict

參數說明：

參數	類型	必填	說明
voice_id	str	是	要查詢的音色ID。

傳回值：dict，音色詳情。

update_voice() - 更新音色

方法簽名：

def update_voice(self, voice_id: str, url: str, language_hints: List[str] = None,
                 max_prompt_audio_length: float = None, enable_preprocess: bool = None) -> None

參數說明：

參數	類型	必填	說明
voice_id	str	是	要更新的音色ID。
url	str	是	新的音頻檔案URL。
language_hints	List[str]	否	樣本音頻語種提示。
max_prompt_audio_length	float	否	參考音頻最大時間長度。
enable_preprocess	bool	否	是否開啟音頻預先處理。

delete_voice() - 刪除音色

方法簽名：

def delete_voice(self, voice_id: str) -> None

參數說明：

參數	類型	必填	說明
voice_id	str	是	要刪除的音色ID。