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

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

使用者指南：聲音複刻。

服務端點

國際

服務部署範圍為國際時，模型推理計算資源在全球範圍內動態調度（不含中國內地）；待用資料儲存於您所選的地區。該部署範圍支援的地區：新加坡。

POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization

中國內地

服務部署範圍為中國內地時，模型推理計算資源僅限於中國內地；待用資料儲存於您所選的地區。該部署範圍支援的地區：華北2（北京）。

POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization

要求標頭

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

建立音色

請求體	以下為新加坡地區URL，若使用北京地區的模型，需將URL替換為：`https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization`。 CosyVoice聲音複刻 `curl -X POST https://dashscope-intl.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": "cosyvoice-v3-plus", "prefix": "myvoice", "url": "https://your-audio-url.wav", "language_hints": ["zh"] } }'` Qwen聲音複刻 `curl -X POST https://dashscope-intl.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`：CosyVoice聲音複刻。 `qwen-voice-enrollment`：Qwen聲音複刻。
input `object` （必選）輸入參數對象。屬性 action `string` （必選）操作類型。 CosyVoice（`voice-enrollment`）：固定為`create_voice`。 Qwen（`qwen-voice-enrollment`）：固定為`create`。 target_model `string` （必選）驅動音色的語音合成模型。必須與後續調用語音合成介面時使用的模型一致，否則合成會失敗。 url `string` （條件必選）重要僅適用於CosyVoice聲音複刻（model為`voice-enrollment`時）。用於複刻音色的音頻檔案URL，要求公網可訪問。 audio `object` （條件必選）重要僅適用於Qwen聲音複刻（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聲音複刻（model為`qwen-voice-enrollment`時）。音頻對應的常值內容，用於輔助提升複刻效果。 prefix `string` （條件必選）重要僅適用於CosyVoice（model為`voice-enrollment`時）。音色名稱首碼，僅允許數字和英文字母，不超過10個字元。產生的音色名格式：`{target_model}-{prefix}-{唯一標識}`。 preferred_name `string` （條件必選）重要僅適用於Qwen聲音複刻（model為`qwen-voice-enrollment`時）。音色名稱首碼，僅允許數字、英文字母和底線，不超過16個字元。 language_hints `array[string]` （可選）重要僅適用於CosyVoice聲音複刻（model為`voice-enrollment`時），且僅cosyvoice-v3.5-plus、v3.5-flash、v3-plus和v3-flash模型支援。輔助模型識別樣本音訊語種，從而更準確地提取音色特徵，提升複刻效果。若設定的語種與實際音頻語種不符（例如為中文音頻設定 `en`），系統將忽略該設定並自動檢測語種。此參數為數組，但目前的版本僅處理第一個元素。取值範圍（因模型而異）： 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聲音複刻（model為`qwen-voice-enrollment`時）。指定 `audio.data` 音頻對應的語種。若使用該參數，設定的語種須與實際用於複刻的音頻語種一致。取值範圍： zh：中文 en：英文 de：德語 it：意大利語 pt：葡萄牙語 es：西班牙語 ja：日語 ko：韓語 fr：法語 ru：俄語預設值：zh。 max_prompt_audio_length `float` （可選）重要僅適用於CosyVoice聲音複刻（model為`voice-enrollment`時），且僅cosyvoice-v3.5-plus、v3.5-flash和v3-flash模型支援。音頻預先處理後用於聲音複刻的參考音頻最大時間長度（秒）。取值範圍：[3.0, 30.0]。時間越長效果越好。預設值：10.0。 enable_preprocess `boolean` （可選）重要僅適用於CosyVoice聲音複刻（model為`voice-enrollment`時），且僅cosyvoice-v3.5-plus、v3.5-flash和v3-flash模型支援。是否開啟音頻預先處理（降噪、音頻增強、音量規整）。有背景雜音時建議開啟；安靜環境建議關閉以最大程度還原音色。預設值：false。

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

查詢音色列表

請求體

以下為新加坡地區URL，若使用北京地區的模型，需將URL替換為：https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization。

CosyVoice

curl -X POST https://dashscope-intl.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聲音複刻

curl -X POST https://dashscope-intl.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：CosyVoice聲音複刻。
qwen-voice-enrollment：Qwen聲音複刻。

input object （必選）

輸入參數對象。

屬性

action string （必選）

操作類型。CosyVoice：list_voice。Qwen：list。

prefix string （可選）

重要

僅適用於CosyVoice。

按首碼篩選音色。

page_index integer （可選）

頁碼索引。

page_size integer （可選）

每頁包含資料條數。

返回體	CosyVoice `{ "output": { "voice_list": [ { "voice_id": "cosyvoice-v3.5-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" }` 重要 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]` 查詢到的音色列表。CosyVoice和Qwen均使用`voice_list`欄位名。屬性 voice_id / voice `string` 音色ID。CosyVoice為`voice_id`，Qwen為`voice`。 gmt_create `string` 建立時間。 gmt_modified `string` 修改時間。 status `string` 重要僅CosyVoice返回。音色狀態，取值參見"音色狀態說明"。 target_model `string` 重要僅Qwen返回。驅動音色的語音合成模型。
usage `object` 本次請求用量資訊。屬性 count `integer` CosyVoice固定為1。Qwen固定為0。

查詢音色詳情

重要

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

請求體

以下為新加坡地區URL，若使用北京地區的模型，需將URL替換為：https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization。

CosyVoice

curl -X POST https://dashscope-intl.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（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": "cosyvoice-v3.5-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。

更新音色

重要

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

請求體

以下為新加坡地區URL，若使用北京地區的模型，需將URL替換為：https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization。

curl -X POST https://dashscope-intl.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。

刪除音色

請求體

以下為新加坡地區URL，若使用北京地區的模型，需將URL替換為：https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization。

CosyVoice

curl -X POST https://dashscope-intl.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聲音複刻

curl -X POST https://dashscope-intl.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：CosyVoice聲音複刻。
qwen-voice-enrollment：Qwen聲音複刻。

input object （必選）

輸入參數對象。

屬性

action string （必選）

操作類型。CosyVoice：delete_voice。Qwen：delete。

voice_id string （條件必選）

重要

僅適用於CosyVoice。

要刪除的音色ID。

voice string （條件必選）

重要

僅適用於Qwen。

要刪除的音色名稱。

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

音色狀態說明

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

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

服務端點

國際

中國內地

要求標頭

建立音色

請求體

CosyVoice聲音複刻

Qwen聲音複刻

返回體

CosyVoice聲音複刻

Qwen聲音複刻

查詢音色列表

請求體

CosyVoice

Qwen聲音複刻

返回體

CosyVoice

Qwen

查詢音色詳情

請求體

CosyVoice

返回體

更新音色

請求體

返回體

刪除音色

請求體

CosyVoice

Qwen聲音複刻

返回體

CosyVoice

Qwen

音色狀態說明