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

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

使用者指南：聲音複刻。

介面地址

SDK的介面地址需在初始化前設定為下方地址（包含WorkspaceId）。如需切換到其他地區，請修改 dashscope.base_http_api_url為對應地區的URL。

新加坡

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1

調用時請將{WorkspaceId}替換為真實的Workspace ID。

華北2（北京）

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1

調用時請將{WorkspaceId}替換為真實的Workspace ID。

切換到新加坡地區：

import dashscope

# 調用時請將"{WorkspaceId}"替換為真實的業務空間ID
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

注意：

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

VoiceEnrollmentService 類

包路徑：dashscope.audio.tts_v2.VoiceEnrollmentService

功能：管理Qwen-Audio-TTS/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,
                 **kwargs) -> str

參數說明：

參數	類型	必填	說明
target_model	str	是	驅動音色的語音合成模型。必須與後續調用語音合成介面時使用的模型一致，否則合成會失敗。
prefix	str	是	音色名稱首碼，僅允許數字和英文字母，不超過10個字元。產生的音色名格式：{target_model}-{prefix}-{唯一標識}。
url	str	是	用於複刻音色的音頻檔案URL，要求公網可訪問。
language_hints	List[str]	否	僅適用於Qwen-Audio-TTS/CosyVoice聲音複刻（model為voice-enrollment時），且僅qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、cosyvoice-v3.5-plus、v3.5-flash、v3-plus和v3-flash模型支援。 輔助模型識別樣本音訊語種，從而更準確地提取音色特徵，提升複刻效果。若設定的語種與實際音頻語種不符（例如為中文音頻設定 en），系統將忽略該設定並自動檢測語種。 此參數為數組，但目前的版本僅處理第一個元素。 取值範圍（因模型而異）： qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash： zh：中文 en：英語 fr：法語 de：德語 ja：日語 ko：韓語 ru：俄語 pt：葡萄牙語 th：泰語 id：印尼語 vi：越南語 it：意大利語 es：西班牙語 ms：馬來西亞語 fil：菲律賓語 ar：阿拉伯語 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	否	僅適用於Qwen-Audio-TTS/CosyVoice聲音複刻（model為voice-enrollment時），且僅qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、cosyvoice-v3.5-plus、v3.5-flash和v3-flash模型支援。 音頻預先處理後用於聲音複刻的參考音頻最大時間長度（秒）。取值範圍：[3.0, 30.0]。 預設值：10.0。
enable_preprocess	bool	否	僅適用於Qwen-Audio-TTS/CosyVoice聲音複刻（model為voice-enrollment時），且僅qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、cosyvoice-v3.5-plus、v3.5-flash和v3-flash模型支援。 是否開啟音頻預先處理（降噪、音頻增強、音量規整）。有背景雜音時建議開啟；安靜環境建議關閉以最大程度還原音色。 預設值：false。
enable_volume_normalization	bool	否	是否對用於聲音複刻的樣本音頻進行音量歸一化。通過關鍵字參數直接傳入。預設值為False。設定為True後，使用所建立音色合成的音頻，其音量可能與關閉該參數時建立的音色不同。

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

list_voices() - 查詢音色列表

方法簽名：

def list_voices(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。

範例程式碼

建立音色

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# 以下為華北2（北京）地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

TARGET_MODEL = 'qwen-audio-3.0-tts-flash'
voice_prefix = 'myvoice'
url = 'https://your-audio-file-url'
service = VoiceEnrollmentService()

# 避免頻繁調用。每次調用都會建立新音色，達到配額上限後將無法建立。
voice_id = service.create_voice(
    target_model=TARGET_MODEL,
    prefix=voice_prefix,
    url=url,
    max_prompt_audio_length=10,
    # enable_preprocess=False,
    # enable_volume_normalization=True
)

print(f"Request ID: {service.get_last_request_id()}")
print(f"Voice ID: {voice_id}")

查詢音色列表

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# 以下為華北2（北京）地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

service = VoiceEnrollmentService()

# 按首碼篩選，或設為None查詢所有
voices = service.list_voices(prefix='myvoice', page_index=0, page_size=10)

print(f"Request ID: {service.get_last_request_id()}")
print(f"Found voices: {voices}")

查詢特定音色

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# 以下為華北2（北京）地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

service = VoiceEnrollmentService()
voice_id = 'qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx'

voice_details = service.query_voice(voice_id=voice_id)

print(f"Request ID: {service.get_last_request_id()}")
print(f"Voice Details: {voice_details}")

更新音色

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# 以下為華北2（北京）地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

service = VoiceEnrollmentService()
service.update_voice(
    voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx',
    url='https://your-new-audio-file-url'
)
print(f"Update submitted. Request ID: {service.get_last_request_id()}")

刪除音色

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# 以下為華北2（北京）地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

service = VoiceEnrollmentService()
service.delete_voice(voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx')
print(f"Deletion submitted. Request ID: {service.get_last_request_id()}")