Skip to main content

聲音複刻Python SDK參考

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

介面地址

SDK的介面地址需在初始化前設定為下方地址（包含WorkspaceId）。如需切換到其他地區，請修改 dashscope.base_http_api_url為對應地區的URL。
  • 不同地區的 API Key 不同，呼叫時需使用對應地區的 API Key。
  • 地區設定為全域設定，影響所有 DashScope SDK API 呼叫。
  • 新加坡
  • 華北2（北京）
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1調用時請將{WorkspaceId}替換為真實的Workspace ID。
阿里雲百鍊為華北2（北京）、新加坡地區推出了業務空間專屬網域名稱，能夠為推理請求提供卓越的效能和更高的穩定性，建議遷移至新網域名稱：
  • 華北2（北京）地區：從 dashscope.aliyuncs.com 遷移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地區：從 dashscope-intl.aliyuncs.com 遷移至 {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

VoiceEnrollmentService 類

包路徑：dashscope.audio.tts_v2.VoiceEnrollmentService 功能：管理 Qwen-Audio-TTS、Qwen-Audio-Realtime 和 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_modelstr是驅動音色的目標模型。必須與後續使用該音色的模型一致，否則呼叫失敗。
prefixstr是音色名稱首碼，僅允許數字和英文字母，不超過10個字元。產生的音色名格式：{target_model}-{prefix}-{唯一標識}。
urlstr是用於複刻音色的參考音訊，支援可公開存取的 URL 或 Base64 Data URI，例如 data:audio/wav;base64,...。
language_hintsList[str]否輔助模型識別樣本音訊語種，從而更準確地提取音色特徵，提升複刻效果。若設定的語種與實際音頻語種不符（例如為中文音頻設定 en），系統將忽略該設定並自動檢測語種。此參數為陣列，長度必須為 1。
適用於 qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash、cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-plus、cosyvoice-v3-flash。
  • qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-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_lengthfloat否音頻預先處理後用於聲音複刻的參考音頻最大時間長度（秒）。取值範圍：[3.0, 30.0]。預設值：10.0。
適用於 qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash、cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash。
enable_preprocessbool否是否開啟音頻預先處理（降噪、音頻增強、音量規整）。有背景雜音時建議開啟；安靜環境建議關閉以最大程度還原音色。預設值：false。
適用於 qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash、cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash。
enable_volume_normalizationbool否是否對用於聲音複刻的樣本音頻進行音量歸一化。通過關鍵字參數直接傳入。預設值為False。設定為True後，使用所建立音色合成的音頻，其音量可能與關閉該參數時建立的音色不同。
傳回值：str，音色ID（voice_id）。

list_voices() - 查詢音色列表

方法簽名： 
def list_voices(self, prefix: str = None, page_index: int = 0, page_size: int = 10) -> list
參數說明：
參數類型必填說明
prefixstr否按音色名稱首碼篩選。
page_indexint否頁碼索引，預設0。
page_sizeint否每頁條數，預設10。
傳回值：list，音色列表。

query_voice() - 查詢音色詳情

方法簽名： 
def query_voice(self, voice_id: str) -> dict
參數說明：
參數類型必填說明
voice_idstr是要查詢的音色ID。
傳回值：dict，音色詳情。

update_voice() - 更新音色

方法簽名： 
def update_voice(self, voice_id: str, url: str) -> None
參數說明：
參數類型必填說明
voice_idstr是要更新的音色ID。
urlstr是新的參考音訊，支援可公開存取的 URL 或 Base64 Data URI，例如 data:audio/wav;base64,...。

delete_voice() - 刪除音色

方法簽名： 
def delete_voice(self, voice_id: str) -> None
參數說明：
參數類型必填說明
voice_idstr是要刪除的音色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}")
使用本機 WAV 音訊時，將上述 url 賦值替換為以下程式碼，再呼叫 create_voice。更新音色時，也透過 update_voice 的 url 參數傳入 Data URI。將 sample.wav 替換為本機音訊路徑。 
import base64
from pathlib import Path

url = "data:audio/wav;base64," + base64.b64encode(
    Path("sample.wav").read_bytes()
).decode("ascii")

查詢音色列表 

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()}")