聲音複刻HTTP API參考 - Alibaba Cloud Model Studio

本文介紹聲音複刻的HTTP API介面詳情，包括建立音色、查詢音色列表、查詢音色詳情、更新音色和刪除音色等操作。

使用者指南：聲音複刻。

服務端點

新加坡

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization

調用時請將{WorkspaceId}替換為真實的Workspace ID。

華北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
新加坡地區：從 dashscope-intl.aliyuncs.com 遷移至 {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId}需要替換為真實的Workspace ID。現有網域名稱仍可正常使用。

要求標頭

參數	類型	是否必選	說明
Authorization	string	是	鑒權令牌，格式為`Bearer <your_api_key>`，使用時，將"`<your_api_key>`"替換為實際的API Key。
Content-Type	string	是	請求體的媒體類型。Qwen-Audio-TTS/CosyVoice/Qwen-TTS固定為`application/json`，MiniMax固定為`application/json; charset=utf-8`。

建立音色

請求體	以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。 Qwen-Audio-TTS/CosyVoice聲音複刻 `curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "voice-enrollment", "input": { "action": "create_voice", "target_model": "qwen-audio-3.0-tts-plus", "prefix": "myvoice", "url": "https://your-audio-url.wav", "language_hints": ["zh"] } }'` Qwen-TTS聲音複刻 `curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-voice-enrollment", "input": { "action": "create", "target_model": "qwen3-tts-vc-realtime-2026-01-15", "preferred_name": "myvoice", "audio": {"data": "data:audio/mpeg;base64,{base64_encoded_audio}"} } }'`
model `string` （必選）聲音複刻模型。取值： `voice-enrollment`：Qwen-Audio-TTS/CosyVoice聲音複刻。 `qwen-voice-enrollment`：Qwen-TTS聲音複刻。
input `object` （必選）輸入參數對象。屬性 action `string` （必選）操作類型。 Qwen-Audio-TTS/CosyVoice（`voice-enrollment`）：固定為`create_voice`。 Qwen（`qwen-voice-enrollment`）：固定為`create`。 target_model `string` （必選）驅動音色的語音合成模型。必須與後續調用語音合成介面時使用的模型一致，否則合成會失敗。 url `string` （條件必選）重要僅適用於Qwen-Audio-TTS/CosyVoice聲音複刻（model為`voice-enrollment`時）。用於複刻音色的音頻檔案URL，要求公網可訪問。 audio `object` （條件必選）重要僅適用於Qwen-TTS聲音複刻（model為`qwen-voice-enrollment`時）。音頻資料，支援兩種提交方式： Data URL（Base64編碼）：格式為`{"data": "data:{mime_type};base64,{base64_encoded_data}"}`，支援的MIME類型：`audio/wav`、`audio/mpeg`、`audio/mp4`。音頻URL：格式為`{"data": "https://your-audio-url.wav"}`，URL必須公網可訪問且無需鑒權。 text `string` （可選）重要僅適用於Qwen-TTS聲音複刻（model為`qwen-voice-enrollment`時）。音頻對應的常值內容，用於輔助提升複刻效果。 prefix `string` （條件必選）重要僅適用於Qwen-Audio-TTS/CosyVoice（model為`voice-enrollment`時）。音色名稱首碼，僅允許數字和英文字母，不超過10個字元。產生的音色名格式：`{target_model}-{prefix}-{唯一標識}`。 preferred_name `string` （條件必選）重要僅適用於Qwen-TTS聲音複刻（model為`qwen-voice-enrollment`時）。音色名稱首碼，僅允許數字、英文字母和底線，不超過16個字元。 language_hints `array[string]` （可選）重要僅適用於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：意大利語 ms：馬來語 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"]。 language `string` （可選）重要僅適用於Qwen-TTS聲音複刻（model為`qwen-voice-enrollment`時）。指定 `audio.data` 音頻對應的語種。若使用該參數，設定的語種須與實際用於複刻的音頻語種一致。取值範圍： zh：中文 en：英文 de：德語 it：意大利語 pt：葡萄牙語 es：西班牙語 ja：日語 ko：韓語 fr：法語 ru：俄語預設值：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 `boolean` （可選）重要僅適用於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。

返回體	Qwen-Audio-TTS/CosyVoice聲音複刻 `{ "output": { "voice_id": "qwen-audio-3.0-tts-plus-myvoice-xxxxxx" }, "usage": { "count": 1 }, "request_id": "xxxx-xxxx-xxxx" }` Qwen-TTS聲音複刻 `{ "output": { "voice": "yourVoice", "target_model": "qwen3-tts-vc-realtime-2026-01-15" }, "usage": { "count": 1 }, "request_id": "xxxx-xxxx-xxxx" }` 重要 Qwen-Audio-TTS/CosyVoice返回`voice_id`欄位，Qwen返回`voice`欄位。Qwen-TTS聲音複刻還可能返回`fallback_mode`和`fallback_reason`欄位。
request_id `string` 本次調用的唯一識別碼。
output `object` 模型返回的資料。屬性 voice_id / voice `string` 音色ID。Qwen-Audio-TTS/CosyVoice返回`voice_id`，Qwen返回`voice`。可直接用於語音合成介面的voice參數。 target_model `string` 重要僅Qwen返回。驅動音色的語音合成模型。 fallback_mode `boolean` 重要僅適用於Qwen-TTS聲音複刻（model為`qwen-voice-enrollment`時）。是否以降級模式建立音色。當音頻品質不佳或與文本不匹配時，該值為`true`，表示複刻效果可能不理想。 fallback_reason `string` 重要僅當`fallback_mode`為`true`時返回。降級原因。可能的值包括`no_merged_segments`（無法合并音頻片段）、`no_valid_asr_segments`（音頻與文本嚴重不匹配）等。
usage `object` 本次請求用量資訊。屬性 count `integer` 建立的音色數量，固定為1。

查詢音色列表

請求體

以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。

Qwen-Audio-TTS/CosyVoice

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "list_voice",
        "prefix": "myvoice",
        "page_size": 10,
        "page_index": 0
    }
}'

Qwen-TTS聲音複刻

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-enrollment",
    "input": {
        "action": "list",
        "page_size": 10,
        "page_index": 0
    }
}'

model string （必選）

聲音複刻模型。取值：

voice-enrollment：Qwen-Audio-TTS/CosyVoice聲音複刻。
qwen-voice-enrollment：Qwen-TTS聲音複刻。

input object （必選）

輸入參數對象。

屬性

action string （必選）

操作類型。Qwen-Audio-TTS/CosyVoice：list_voice。Qwen：list。

prefix string （可選）

重要

僅適用於Qwen-Audio-TTS/CosyVoice。

按首碼篩選音色。

page_index integer （可選）

頁碼索引。

page_size integer （可選）

每頁包含資料條數。

返回體	Qwen-Audio-TTS/CosyVoice `{ "output": { "voice_list": [ { "voice_id": "qwen-audio-3.0-tts-plus-myvoice-xxxxxx", "gmt_create": "2024-12-11 13:38:02", "gmt_modified": "2024-12-11 13:38:02", "status": "OK" } ] }, "usage": { "count": 1 }, "request_id": "xxxx-xxxx-xxxx" }` Qwen `{ "output": { "page_index": 0, "page_size": 10, "total_count": 2, "voice_list": [ { "voice": "yourVoice1", "gmt_create": "2025-08-11 17:59:32", "gmt_modified": "2025-08-11 17:59:32", "language": "zh", "target_model": "qwen3-tts-vc-realtime-2026-01-15" } ] }, "usage": { "count": 0 }, "request_id": "xxxx-xxxx-xxxx" }` 重要 Qwen-Audio-TTS/CosyVoice返回`voice_list`數組，每項包含`voice_id`欄位；Qwen同樣返回`voice_list`數組，每項包含`voice`欄位。Qwen的output中還包含`page_index`、`page_size`和`total_count`分頁資訊欄位。
request_id `string` 本次調用的唯一識別碼。
output `object` 模型返回的資料。屬性 page_index `integer` 重要僅Qwen返回。當前頁碼索引。 page_size `integer` 重要僅Qwen返回。每頁資料條數。 total_count `integer` 重要僅Qwen返回。音色總數。 voice_list `array[object]` 查詢到的音色列表。Qwen-Audio-TTS/CosyVoice和Qwen均使用`voice_list`欄位名。屬性 voice_id / voice `string` 音色ID。Qwen-Audio-TTS/CosyVoice為`voice_id`，Qwen為`voice`。 gmt_create `string` 建立時間。 gmt_modified `string` 修改時間。 status `string` 重要僅Qwen-Audio-TTS/CosyVoice返回。音色狀態，取值參見"音色狀態說明"。 target_model `string` 重要僅Qwen返回。驅動音色的語音合成模型。
usage `object` 本次請求用量資訊。屬性 count `integer` Qwen-Audio-TTS/CosyVoice固定為1。Qwen固定為0。

查詢音色詳情

重要

僅適用於Qwen-Audio-TTS/CosyVoice（model為voice-enrollment時）。Qwen模型不支援查詢音色詳情操作。

請求體

以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。

Qwen-Audio-TTS/CosyVoice

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "query_voice",
        "voice_id": "yourVoiceId"
    }
}'

model string （必選）

固定為voice-enrollment（Qwen-Audio-TTS/CosyVoice）。

input object （必選）

輸入參數對象。

屬性

action string （必選）

固定為query_voice。

voice_id string （必選）

要查詢的音色ID。

返回體	`{ "output": { "gmt_create": "2024-12-11 13:38:02", "resource_link": "https://yourAudioFileUrl", "target_model": "qwen-audio-3.0-tts-plus", "gmt_modified": "2024-12-11 13:38:02", "status": "OK" }, "usage": { "count": 1 }, "request_id": "xxxx-xxxx-xxxx" }`
request_id `string` 本次調用的唯一識別碼。
output `object` 模型返回的資料。屬性 resource_link `string` 音頻檔案的URL地址。 gmt_create `string` 建立時間。 gmt_modified `string` 修改時間。 status `string` 音色狀態，取值參見"音色狀態說明"。 target_model `string` 驅動音色的語音合成模型。
usage `object` 本次請求用量資訊。屬性 count `integer` 固定為1。

更新音色

重要

僅適用於Qwen-Audio-TTS/CosyVoice聲音複刻（model為voice-enrollment時）。Qwen模型不支援更新操作。

請求體

以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "update_voice",
        "voice_id": "yourVoiceId",
        "url": "https://new-audio-url.wav"
    }
}'

model string （必選）

固定為voice-enrollment。

input object （必選）

輸入參數對象。

屬性

action string （必選）

固定為update_voice。

voice_id string （必選）

要更新的音色ID。

url string （必選）

新的音頻檔案URL，要求公網可訪問。

返回體	`{ "output": {}, "usage": { "count": 1 }, "request_id": "xxxx-xxxx-xxxx" }`
request_id `string` 本次調用的唯一識別碼。
output `object` 模型返回的資料，更新操作返回Null 物件。
usage `object` 本次請求用量資訊。屬性 count `integer` 固定為1。

刪除音色

請求體

以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。

Qwen-Audio-TTS/CosyVoice

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "delete_voice",
        "voice_id": "yourVoiceId"
    }
}'

Qwen-TTS聲音複刻

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-enrollment",
    "input": {
        "action": "delete",
        "voice": "yourVoice"
    }
}'

model string （必選）

聲音複刻模型。取值：

voice-enrollment：Qwen-Audio-TTS/CosyVoice聲音複刻。
qwen-voice-enrollment：Qwen-TTS聲音複刻。

input object （必選）

輸入參數對象。

屬性

action string （必選）

操作類型。Qwen-Audio-TTS/CosyVoice：delete_voice。Qwen：delete。

voice_id string （條件必選）

重要

僅適用於Qwen-Audio-TTS/CosyVoice。

要刪除的音色ID。

voice string （條件必選）

重要

僅適用於Qwen。

要刪除的音色名稱。

返回體	Qwen-Audio-TTS/CosyVoice `{ "output": {}, "usage": { "count": 1 }, "request_id": "xxxx-xxxx-xxxx" }` Qwen `{ "output": { "voice": "yourVoice" }, "usage": { "count": 0 }, "request_id": "xxxx-xxxx-xxxx" }` 重要 Qwen-Audio-TTS/CosyVoice的output為空白對象，Qwen返回`voice`欄位。
request_id `string` 本次調用的唯一識別碼。
output `object` 模型返回的資料。Qwen-Audio-TTS/CosyVoice返回Null 物件，Qwen返回已刪除的音色名稱。屬性 voice `string` 重要僅Qwen返回。已刪除的音色名稱。
usage `object` 本次請求用量資訊。屬性 count `integer` 固定為1。

音色狀態說明

音色建立後會經過審核流程，以下是各狀態的含義。此狀態體系僅適用於Qwen-Audio-TTS/CosyVoice（model為voice-enrollment時），Qwen的查詢和列表返回中不包含status欄位。

狀態	說明
DEPLOYING	審核中/處理中。
OK	審核通過，可正常使用。
UNDEPLOYED	審核未通過，不可使用。

服務端點

新加坡

華北2（北京）

要求標頭

建立音色

請求體

Qwen-Audio-TTS/CosyVoice聲音複刻

Qwen-TTS聲音複刻

返回體

Qwen-Audio-TTS/CosyVoice聲音複刻

Qwen-TTS聲音複刻

查詢音色列表

請求體

Qwen-Audio-TTS/CosyVoice

Qwen-TTS聲音複刻

返回體

Qwen-Audio-TTS/CosyVoice

Qwen

查詢音色詳情

請求體

Qwen-Audio-TTS/CosyVoice

返回體

更新音色

請求體

返回體

刪除音色

請求體

Qwen-Audio-TTS/CosyVoice

Qwen-TTS聲音複刻

返回體

Qwen-Audio-TTS/CosyVoice

Qwen

音色狀態說明