本文介紹聲音設計的HTTP API介面詳情,包括建立音色、查詢音色列表、查詢音色詳情和刪除音色四個操作。
使用者指南:聲音設計。
介面地址
華北2(北京)
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization
調用時請將{WorkspaceId}替換為真實的Workspace ID。
重要阿里雲百鍊為華北2(北京)地區推出了業務空間專屬網域名稱,能夠為推理請求提供卓越的效能和更高的穩定性,建議遷移至新網域名稱:
- 華北2(北京)地區:從
dashscope.aliyuncs.com 遷移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com
{WorkspaceId}需要替換為真實的Workspace ID。現有網域名稱仍可正常使用。
要求標頭
參數 | 類型 | 是否必選 | 說明 |
|---|
Authorization | string | 是 | 鑒權令牌,格式為Bearer <your_api_key>,使用時,將"<your_api_key>"替換為實際的API Key。 |
Content-Type | string | 是 | 請求體的媒體類型。固定為application/json。 |
建立音色
請求體 modelstring(必選) 聲音設計模型。取值:
voice-enrollment:Qwen-Audio-TTS/CosyVoice聲音設計。
inputobject(必選) 輸入參數對象。 屬性 action string(必選) 操作類型。
- Qwen-Audio-TTS/CosyVoice(
voice-enrollment):固定為create_voice。
target_model string(必選) 驅動音色的語音合成模型。必須與後續調用語音合成介面時使用的模型一致,否則合成會失敗。 qwen-audio-3.0-tts-plus和qwen-audio-3.0-tts-flash不支援聲音設計。 voice_prompt string(必選) 聲音描述文本,僅支援中文和英文。
- Qwen-Audio-TTS/CosyVoice(
voice-enrollment):最大長度500字元。
preview_text string(必選) 預覽音頻對應的文本。
- Qwen-Audio-TTS/CosyVoice(
voice-enrollment):最小長度15字元,最大長度200字元,支援中文和英文。
prefix string(必選) 重要僅適用於Qwen-Audio-TTS/CosyVoice(model為voice-enrollment時)。 音色名稱首碼,僅允許數字和英文字母,不超過10個字元。產生的音色名格式:{target_model}-vd-{prefix}-{唯一標識} language_hints array[string](可選) 重要僅適用於Qwen-Audio-TTS/CosyVoice(model為voice-enrollment時)。 指定產生音色的語言傾向,影響音色的語言特徵和發音傾向,建議根據實際使用情境選擇對應語言代碼。若使用該參數,設定的語種須與 preview_text 的語種一致。 此參數為數組,但目前的版本僅處理第一個元素。 取值範圍: 預設值:["zh"]。 parametersobject(可選) 聲音設計的參數配置。 屬性 sample_rate int(可選) 預覽音頻採樣率(Hz)。
- Qwen-Audio-TTS/CosyVoice支援:16000、24000、48000。
預設值:24000。 response_format string(可選) 預覽音頻格式。
- Qwen-Audio-TTS/CosyVoice支援:pcm、wav、mp3。
預設值:wav。 | 以下範例使用華北2(北京)地區的設定,呼叫時請將 {WorkspaceId} 替換為真實的業務空間 ID。 |
返回體 request_idstring 本次調用的唯一識別碼。 outputobject 模型返回的資料。 屬性 voice_idstring 音色 ID,可用於語音合成介面的 voice 參數。 preview_audioobject 預覽音頻資料。 屬性 data string 預覽音頻資料,Base64編碼。 sample_rate int 預覽音頻採樣率(Hz)。 response_format string 預覽音頻格式。 target_modelstring 驅動音色的語音合成模型。 usageobject 本次請求用量資訊。 屬性 count integer 建立的音色數量,固定為1。 | |
查詢音色列表
請求體 modelstring(必選) 聲音設計模型。取值:
voice-enrollment:Qwen-Audio-TTS/CosyVoice聲音設計。
inputobject(必選) 輸入參數對象。 屬性 action string(必選) 固定為 list_voice。 prefix string(可選) 重要僅適用於Qwen-Audio-TTS/CosyVoice。 按首碼篩選音色。 page_index integer(可選) 頁碼索引。 page_size integer(可選) 每頁包含資料條數。 | 以下範例使用華北2(北京)地區的設定,呼叫時請將 {WorkspaceId} 替換為真實的業務空間 ID。 |
返回體 request_idstring 本次調用的唯一識別碼。 outputobject 模型返回的資料。 屬性 voice_listarray[object] 查詢到的音色列表。 屬性 voice_idstring 音色 ID,可用於語音合成介面的 voice 參數。 gmt_createstring 建立時間。 gmt_modifiedstring 修改時間。 statusstring 重要僅Qwen-Audio-TTS/CosyVoice返回。 音色狀態,取值參見"音色狀態說明"。 voice_promptstring 聲音描述文本。 preview_textstring 預覽音頻文本。 usageobject 本次請求用量資訊。 | |
查詢音色詳情
請求體 modelstring(必選) 聲音設計模型。取值:
voice-enrollment:Qwen-Audio-TTS/CosyVoice聲音設計。
inputobject(必選) 輸入參數對象。 屬性 action string(必選) 固定為 query_voice。 voice_id string(必選) 重要僅適用於Qwen-Audio-TTS/CosyVoice。 要查詢的音色ID。 | 以下範例使用華北2(北京)地區的設定,呼叫時請將 {WorkspaceId} 替換為真實的業務空間 ID。 |
返回體 request_idstring 本次調用的唯一識別碼。 outputobject 模型返回的資料。 屬性 voice_idstring 音色 ID,可用於語音合成介面的 voice 參數。 gmt_createstring 建立時間。 gmt_modifiedstring 修改時間。 statusstring 重要僅Qwen-Audio-TTS/CosyVoice返回。 音色狀態,取值參見"音色狀態說明"。 target_modelstring 驅動音色的語音合成模型。 voice_promptstring 重要僅Qwen-Audio-TTS/CosyVoice聲音設計返回。 聲音描述文本。 preview_textstring 重要僅Qwen-Audio-TTS/CosyVoice聲音設計返回。 預覽音頻文本。 usageobject 本次請求用量資訊。 | |
刪除音色
請求體 modelstring(必選) 聲音設計模型。取值:
voice-enrollment:Qwen-Audio-TTS/CosyVoice聲音設計。
inputobject(必選) 輸入參數對象。 屬性 action string(必選) 固定為 delete_voice。 voice_id string(必選) 重要僅適用於Qwen-Audio-TTS/CosyVoice。 要刪除的音色ID。 | 以下範例使用華北2(北京)地區的設定,呼叫時請將 {WorkspaceId} 替換為真實的業務空間 ID。 |
返回體 request_idstring 本次調用的唯一識別碼。 outputobject 模型返回的資料,為空物件。 usageobject 本次請求用量資訊。 | |
音色狀態說明
音色建立後會經過審核流程。以下狀態適用於 Qwen-Audio-TTS/CosyVoice(model 為 voice-enrollment)。
狀態 | 說明 |
|---|
DEPLOYING | 審核中/處理中。 |
OK | 審核通過,可正常使用。 |
UNDEPLOYED | 審核未通過,不可使用。 |