透過 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個字元。產生的音色名格式: |
url | str | 是 | 用於複刻音色的參考音訊,支援可公開存取的 URL 或 Base64 Data URI,例如 |
language_hints | List[str] | 否 | 輔助模型識別樣本音訊語種,從而更準確地提取音色特徵,提升複刻效果。若設定的語種與實際音頻語種不符(例如為中文音頻設定 此參數為陣列,長度必須為 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。 點擊查看各模型支援的語言
預設值:["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 | 否 | 是否對用於聲音複刻的樣本音頻進行音量歸一化。通過 |
傳回值: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,例如 |
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}")