聲音設計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	是	請求體的媒體類型。固定為`application/json`。

建立音色

請求體	以下為新加坡地區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.5-plus", "voice_prompt": "沉穩的中年男性，音色低沉渾厚", "preview_text": "各位聽眾朋友，大家好", "prefix": "announcer", "language_hints": ["zh"] }, "parameters": { "sample_rate": 24000, "response_format": "wav" } }' 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-design", "input": { "action": "create", "target_model": "qwen3-tts-vd-realtime-2026-01-15", "preferred_name": "announcer", "voice_prompt": "沉穩的中年男性，音色低沉渾厚", "preview_text": "各位聽眾朋友，大家好", "language": "zh" }, "parameters": { "sample_rate": 24000, "response_format": "wav" } }'
model `string` （必選）聲音設計模型。取值： `voice-enrollment`：CosyVoice聲音設計。 `qwen-voice-design`：Qwen聲音設計。
input `object` （必選）輸入參數對象。屬性 action `string` （必選）操作類型。 CosyVoice（`voice-enrollment`）：固定為`create_voice`。 Qwen（`qwen-voice-design`）：固定為`create`。 target_model `string` （必選）驅動音色的語音合成模型。必須與後續調用語音合成介面時使用的模型一致，否則合成會失敗。 voice_prompt `string` （必選）聲音描述文本，僅支援中文和英文。 CosyVoice（`voice-enrollment`）：最大長度500字元。 Qwen（`qwen-voice-design`）：最大長度2048字元。 preview_text `string` （必選）預覽音頻對應的文本。 CosyVoice（`voice-enrollment`）：最大長度200字元，支援中文和英文。 Qwen（`qwen-voice-design`）：最大長度1024字元，支援中文、英文、德語、意大利語、葡萄牙語、西班牙語、日語、韓語、法語、俄語。 prefix `string` （條件必選）重要僅適用於CosyVoice（model為`voice-enrollment`時）。音色名稱首碼，僅允許數字和英文字母，不超過10個字元。產生的音色名格式：`{target_model}-vd-{prefix}-{唯一標識}` preferred_name `string` （條件必選）重要僅適用於Qwen（model為`qwen-voice-design`時）。音色名稱首碼，僅允許數字、英文字母和底線，不超過16個字元。 language_hints `array[string]` （可選）重要僅適用於CosyVoice（model為`voice-enrollment`時）。指定產生音色的語言傾向，影響音色的語言特徵和發音傾向，建議根據實際使用情境選擇對應語言代碼。若使用該參數，設定的語種須與 `preview_text` 的語種一致。此參數為數組，但目前的版本僅處理第一個元素。取值範圍： zh：中文 en：英文預設值：["zh"]。 language `string` （可選）重要僅適用於Qwen（model為`qwen-voice-design`時）。指定產生音色的語言傾向，影響音色的語言特徵和發音傾向，建議根據實際使用情境選擇對應語言代碼。若使用該參數，設定的語種須與 `preview_text` 的語種一致。取值範圍： zh：中文 en：英文 de：德語 it：意大利語 pt：葡萄牙語 es：西班牙語 ja：日語 ko：韓語 fr：法語 ru：俄語預設值：zh。
parameters `object` （可選）聲音設計的參數配置。屬性 sample_rate `int` （可選）預覽音頻採樣率（Hz）。 CosyVoice支援：16000、24000、48000。 Qwen支援：8000、16000、24000、48000。預設值：24000。 response_format `string` （可選）預覽音頻格式。 CosyVoice支援：pcm、wav、mp3。 Qwen支援：pcm、wav、mp3、opus。預設值：wav。

返回體	CosyVoice聲音設計 `{ "output": { "preview_audio": { "data": "{base64_encoded_audio}", "sample_rate": 24000, "response_format": "wav" }, "target_model": "cosyvoice-v3.5-plus", "voice_id": "cosyvoice-v3.5-plus-vd-announcer-xxxxxx" }, "usage": { "count": 1 }, "request_id": "xxxx-xxxx-xxxx" }` Qwen聲音設計 `{ "output": { "preview_audio": { "data": "{base64_encoded_audio}", "sample_rate": 24000, "response_format": "wav" }, "target_model": "qwen3-tts-vd-realtime-2026-01-15", "voice": "yourVoice" }, "usage": { "count": 1 }, "request_id": "xxxx-xxxx-xxxx" }` 重要 CosyVoice返回`voice_id`欄位，Qwen返回`voice`欄位。
request_id `string` 本次調用的唯一識別碼。
output `object` 模型返回的資料。屬性 voice_id / voice `string` 音色ID。CosyVoice返回`voice_id`，Qwen返回`voice`。可直接用於語音合成介面的voice參數。 preview_audio `object` 預覽音頻資料。屬性 data `string` 預覽音頻資料，Base64編碼。 sample_rate `int` 預覽音頻採樣率（Hz）。 response_format `string` 預覽音頻格式。 target_model `string` 驅動音色的語音合成模型。
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-design",
    "input": {
        "action": "list",
        "page_size": 10,
        "page_index": 0
    }
}'

model string （必選）

聲音設計模型。取值：

voice-enrollment：CosyVoice聲音設計。
qwen-voice-design：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-vd-announcer-xxxxxx", "gmt_create": "2025-12-10 14:54:09", "gmt_modified": "2025-12-10 17:47:48", "status": "OK", "voice_prompt": "沉穩的中年男性播音員", "preview_text": "各位聽眾朋友們，大家好" } ] }, "usage": { "count": 1 }, "request_id": "xxxx-xxxx-xxxx" }` Qwen `{ "output": { "page_index": 0, "page_size": 10, "total_count": 1, "voice_list": [ { "voice": "yourVoice", "gmt_create": "2025-08-11 17:59:32", "gmt_modified": "2025-08-11 17:59:32", "language": "zh", "target_model": "qwen3-tts-vd-realtime-2026-01-15", "voice_prompt": "沉穩的中年男性播音員", "preview_text": "各位聽眾朋友們，大家好" } ] }, "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]` 查詢到的音色列表。屬性 voice_id / voice `string` 音色ID。CosyVoice為`voice_id`，Qwen為`voice`。 gmt_create `string` 建立時間。 gmt_modified `string` 修改時間。 status `string` 重要僅CosyVoice返回。音色狀態，取值參見"音色狀態說明"。 target_model `string` 重要僅Qwen返回。驅動音色的語音合成模型。 language `string` 音色語言。 voice_prompt `string` 聲音描述文本。 preview_text `string` 預覽音頻文本。
usage `object` 本次請求用量資訊。屬性 count `integer` CosyVoice固定為1。Qwen固定為0。

查詢音色詳情

請求體

以下為新加坡地區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"
    }
}'

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-design",
    "input": {
        "action": "query",
        "voice": "yourVoice"
    }
}'

model string （必選）

聲音設計模型。取值：

voice-enrollment：CosyVoice聲音設計。
qwen-voice-design：Qwen聲音設計。

input object （必選）

輸入參數對象。

屬性

action string （必選）

操作類型。CosyVoice：query_voice。Qwen聲音設計：query。

voice_id string （條件必選）

重要

僅適用於CosyVoice。

要查詢的音色ID。

voice string （條件必選）

重要

僅適用於Qwen聲音設計（model為qwen-voice-design時）。

要查詢的音色名稱。

返回體	CosyVoice聲音設計 `{ "output": { "voice_id": "cosyvoice-v3.5-plus-vd-announcer-xxxxxx", "gmt_create": "2025-12-10 14:54:09", "gmt_modified": "2025-12-10 17:47:48", "preview_text": "各位聽眾朋友們，大家好", "target_model": "cosyvoice-v3.5-plus", "status": "OK", "voice_prompt": "沉穩的中年男性播音員，音色低沉渾厚" }, "usage": {}, "request_id": "xxxx-xxxx-xxxx" }` Qwen聲音設計 `{ "output": { "voice": "yourVoice", "gmt_create": "2025-08-11 17:59:32", "gmt_modified": "2025-08-11 17:59:32", "language": "zh", "target_model": "qwen3-tts-vd-realtime-2026-01-15" }, "usage": { "count": 0 }, "request_id": "xxxx-xxxx-xxxx" }` 重要 CosyVoice聲音設計返回`voice_id`、`voice_prompt`等欄位。Qwen聲音設計返回`voice`和`language`欄位。
request_id `string` 本次調用的唯一識別碼。
output `object` 模型返回的資料。屬性 voice_id / voice `string` 音色ID。CosyVoice聲音設計返回`voice_id`，Qwen聲音設計返回`voice`。 gmt_create `string` 建立時間。 gmt_modified `string` 修改時間。 status `string` 重要僅CosyVoice返回。音色狀態，取值參見"音色狀態說明"。 target_model `string` 驅動音色的語音合成模型。 language `string` 重要僅Qwen聲音設計返回。音色語言。 voice_prompt `string` 重要僅CosyVoice聲音設計返回。聲音描述文本。 preview_text `string` 重要僅CosyVoice聲音設計返回。預覽音頻文本。
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-design",
    "input": {
        "action": "delete",
        "voice": "yourVoice"
    }
}'

model string （必選）

聲音設計模型。取值：

voice-enrollment：CosyVoice聲音設計。
qwen-voice-design：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

Qwen聲音設計

返回體

CosyVoice聲音設計

Qwen聲音設計

刪除音色

請求體

CosyVoice

Qwen聲音設計

返回體

CosyVoice

Qwen

音色狀態說明