Skip to main content
聲音複刻

聲音複刻Python SDK參考

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

使用者指南：聲音複刻。

介面地址

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

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()}")
使用 API
文本產生
映像產生
視頻產生
音頻
即時多模態
Realtime API
  • 概述
向量與排序
更多模型
工具包/架構
模型生產
檔案管理
更多
聲音複刻Python SDK參考 - Alibaba Cloud Model Studio