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