全部產品
Search
文件中心

Alibaba Cloud Model Studio:聲音複刻 Python SDK 參考(Qwen-Audio 與 CosyVoice)

更新時間:Nov 18, 2026

透過 DashScope Python SDK 建立、查詢、更新和刪除 Qwen-Audio、CosyVoice 複刻音色。

介面地址

SDK的介面地址由Client構造參數workspace/region決定(對應下方地址,包含WorkspaceId)。如需切換到其他地區,請修改Client構造參數為對應地區的值。

說明

  • 不同地區的 API Key 不同,呼叫時需使用對應地區的 API Key。
  • 地區設定為Client級設定,影響該Client的所有 DashScope SDK API 呼叫。

新加坡

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。

重要阿里雲百鍊為華北2(北京)、新加坡地區推出了業務空間專屬網域名稱,能夠為推理請求提供卓越的效能和更高的穩定性,建議遷移至新網域名稱:

  • 華北2(北京)地區:從 dashscope.aliyuncs.com 遷移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地區:從 dashscope-intl.aliyuncs.com 遷移至 {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

核心資源(client.audio.voices)

功能:管理 Qwen-Audio-TTS、Qwen-Audio-Realtime 和 CosyVoice 複製音色的生命週期(建立、查詢、更新、刪除)。

Client 構造(鑒權與地區)

import os
import dashscope

client = dashscope.Client(
    # 若沒有將API Key配置到環境變數,請將下行替換為您的百鍊API Key:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為中國(北京)地區的配置。調用時請將"{WorkspaceId}"替換為真實的業務空間ID,各地區的配置不同。
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

create() - 建立音色

方法簽名:

def create(self, *, target_model: str, prefix: str, url: str,
           language_hints: List[str] = None,
           max_prompt_audio_length: float = None,
           extra_input: Dict = None,
           parameters: Dict = None, ...) -> Voice

參數說明:

參數類型必填說明

target_model

str

是

驅動音色的目標模型。必須與後續使用該音色的模型一致,否則呼叫失敗。

prefix

str

是

音色名稱首碼,僅允許數字和英文字母,不超過10個字元。產生的音色名格式:{target_model}-{prefix}-{唯一標識}。

url

str

是

用於複刻音色的參考音訊,支援可公開存取的 URL 或 Base64 Data URI,例如 data:audio/wav;base64,...。

language_hints

List[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_length

float

否

音頻預先處理後用於聲音複刻的參考音頻最大時間長度(秒)。取值範圍:[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_preprocess

bool

否

是否開啟音頻預先處理(降噪、音頻增強、音量規整)。有背景雜音時建議開啟;安靜環境建議關閉以最大程度還原音色。

預設值: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_normalization

bool

否

是否對用於聲音複刻的樣本音頻進行音量歸一化。通過extra_input字典傳入。預設值為False。設定為True後,使用所建立音色合成的音頻,其音量可能與關閉該參數時建立的音色不同。

傳回值:Voice對象,其voice_id為音色ID,request_id為請求ID。

list() - 查詢音色列表

方法簽名:

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

參數說明:

參數類型必填說明

prefix

str

否

按音色名稱首碼篩選。

page_index

int

否

頁碼索引,預設0。

page_size

int

否

每頁條數,預設10。

傳回值:VoiceList對象,其voices為音色列表,request_id為請求ID。列表項目為字典,可透過 voice.get("target_model") 取得目標模型 ID。

get() - 查詢音色詳情

方法簽名:

def get(self, voice_id: str, ...) -> Voice

參數說明:

參數類型必填說明

voice_id

str

是

要查詢的音色ID。

傳回值:Voice對象,音色詳情。透過 voice.target_model 取得目標模型 ID。

update() - 更新音色

方法簽名:

def update(self, voice_id: str, *, url: str, ...) -> JobStatus

參數說明:

參數類型必填說明

voice_id

str

是

要更新的音色ID。

url

str

是

新的參考音訊,支援可公開存取的 URL 或 Base64 Data URI,例如 data:audio/wav;base64,...。

delete() - 刪除音色

方法簽名:

def delete(self, voice_id: str, ...) -> JobStatus

參數說明:

參數類型必填說明

voice_id

str

是

要刪除的音色ID。

範例程式碼

建立音色

import os
import dashscope

# 以下為華北2(北京)地區的配置。調用時請將"{WorkspaceId}"替換為真實的業務空間ID,各地區的配置不同。
client = dashscope.Client(
    # 若沒有將API Key配置到環境變數,請將下行替換為您的百鍊API Key:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

TARGET_MODEL = 'qwen-audio-3.1-tts-plus'
voice_prefix = 'myvoice'
url = 'https://your-audio-file-url'

# 避免頻繁調用。每次調用都會建立新音色,達到配額上限後將無法建立。
voice = client.audio.voices.create(
    target_model=TARGET_MODEL,
    prefix=voice_prefix,
    url=url,
    max_prompt_audio_length=10,
    # extra_input={'enable_preprocess': False, 'enable_volume_normalization': True}
)

print(f"Request ID: {voice.request_id}")
print(f"Voice ID: {voice.voice_id}")

使用本機 WAV 音訊時,將上述 url 賦值替換為以下程式碼,再呼叫 client.audio.voices.create()。更新音色時,也透過 client.audio.voices.update() 的 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 os
import dashscope

# 以下為華北2(北京)地區的配置。調用時請將"{WorkspaceId}"替換為真實的業務空間ID,各地區的配置不同。
client = dashscope.Client(
    # 若沒有將API Key配置到環境變數,請將下行替換為您的百鍊API Key:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

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

print(f"Request ID: {voices.request_id}")
print(f"Found voices: {voices.voices}")
for voice in voices.voices:
    print(f"Target model: {voice.get('target_model')}")

查詢特定音色

import os
import dashscope

# 以下為華北2(北京)地區的配置。調用時請將"{WorkspaceId}"替換為真實的業務空間ID,各地區的配置不同。
client = dashscope.Client(
    # 若沒有將API Key配置到環境變數,請將下行替換為您的百鍊API Key:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

voice_id = 'qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx'

voice_details = client.audio.voices.get(voice_id=voice_id)

print(f"Request ID: {voice_details.request_id}")
print(f"Voice Details: {voice_details}")
print(f"Target model: {voice_details.target_model}")

更新音色

import os
import dashscope

# 以下為華北2(北京)地區的配置。調用時請將"{WorkspaceId}"替換為真實的業務空間ID,各地區的配置不同。
client = dashscope.Client(
    # 若沒有將API Key配置到環境變數,請將下行替換為您的百鍊API Key:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

result = client.audio.voices.update(
    voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx',
    url='https://your-new-audio-file-url'
)
print(f"Update submitted. Request ID: {result.request_id}")

刪除音色

import os
import dashscope

# 以下為華北2(北京)地區的配置。調用時請將"{WorkspaceId}"替換為真實的業務空間ID,各地區的配置不同。
client = dashscope.Client(
    # 若沒有將API Key配置到環境變數,請將下行替換為您的百鍊API Key:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

result = client.audio.voices.delete(voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx')
print(f"Deletion submitted. Request ID: {result.request_id}")