聲音設計API參考_Alibaba Cloud Model Studio(Model Studio) - 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	是	請求體的媒體類型。固定為`application/json`。

建立音色

請求體

modelstring（必選）

聲音設計模型。取值：

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

inputobject（必選）

輸入參數對象。

屬性

action string（必選）

操作類型。

Qwen-Audio-TTS/CosyVoice（voice-enrollment）：固定為create_voice。
Qwen（qwen-voice-design）：固定為create。

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字元。
Qwen（qwen-voice-design）：最大長度2048字元。

preview_text string（必選）

預覽音頻對應的文本。

Qwen-Audio-TTS/CosyVoice（voice-enrollment）：最小長度15字元，最大長度200字元，支援中文和英文。
Qwen（qwen-voice-design）：最大長度1024字元，支援中文、英文、德語、意大利語、葡萄牙語、西班牙語、日語、韓語、法語、俄語。

prefix string（條件必選）

重要僅適用於Qwen-Audio-TTS/CosyVoice（model為voice-enrollment時）。

音色名稱首碼，僅允許數字和英文字母，不超過10個字元。產生的音色名格式：{target_model}-vd-{prefix}-{唯一標識}

preferred_name string（條件必選）

重要僅適用於Qwen（model為qwen-voice-design時）。

音色名稱首碼，僅允許數字、英文字母和底線，不超過16個字元。

language_hints array[string]（可選）

重要僅適用於Qwen-Audio-TTS/CosyVoice（model為voice-enrollment時）。

指定產生音色的語言傾向，影響音色的語言特徵和發音傾向，建議根據實際使用情境選擇對應語言代碼。若使用該參數，設定的語種須與 preview_text 的語種一致。

此參數為數組，但目前的版本僅處理第一個元素。

取值範圍：

zh：中文
en：英文

預設值：["zh"]。

language string（可選）

重要僅適用於Qwen（model為qwen-voice-design時）。

取值範圍：

zh：中文
en：英文
de：德語
it：意大利語
pt：葡萄牙語
es：西班牙語
ja：日語
ko：韓語
fr：法語
ru：俄語

預設值：zh。

parametersobject（可選）

聲音設計的參數配置。

屬性

sample_rate int（可選）

預覽音頻採樣率（Hz）。

Qwen-Audio-TTS/CosyVoice支援：16000、24000、48000。
Qwen支援：8000、16000、24000、48000。

預設值：24000。

response_format string（可選）

預覽音頻格式。

Qwen-Audio-TTS/CosyVoice支援：pcm、wav、mp3。
Qwen支援：pcm、wav、mp3、opus。

預設值：wav。

Qwen-Audio-TTS/CosyVoice 聲音設計僅支援北京地區，Qwen 聲音設計支援新加坡地區。以下樣本中 Qwen-Audio-TTS/CosyVoice 使用華北2（北京）地區URL，Qwen 使用新加坡地區URL（請將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": "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://{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-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"
    }
}'

返回體

request_idstring

本次調用的唯一識別碼。

outputobject

模型返回的資料。

屬性

voice_id / voicestring

音色ID。Qwen-Audio-TTS/CosyVoice返回voice_id，Qwen返回voice。可直接用於語音合成介面的voice參數。

preview_audioobject

預覽音頻資料。

屬性

data string

預覽音頻資料，Base64編碼。

sample_rate int

預覽音頻採樣率（Hz）。

response_format string

預覽音頻格式。

target_modelstring

驅動音色的語音合成模型。

usageobject

本次請求用量資訊。

屬性

count integer

建立的音色數量，固定為1。

Qwen-Audio-TTS/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"
}

重要Qwen-Audio-TTS/CosyVoice返回voice_id欄位，Qwen返回voice欄位。

查詢音色列表

請求體

modelstring（必選）

聲音設計模型。取值：

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

inputobject（必選）

輸入參數對象。

屬性

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

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聲音設計

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-design",
    "input": {
        "action": "list",
        "page_size": 10,
        "page_index": 0
    }
}'

返回體

request_idstring

本次調用的唯一識別碼。

outputobject

模型返回的資料。

屬性

page_indexinteger

重要僅Qwen返回。

當前頁碼索引。

page_sizeinteger

重要僅Qwen返回。

每頁資料條數。

total_countinteger

重要僅Qwen返回。

音色總數。

voice_listarray[object]

查詢到的音色列表。

屬性

voice_id / voicestring

音色ID。Qwen-Audio-TTS/CosyVoice為voice_id，Qwen為voice。

gmt_createstring

建立時間。

gmt_modifiedstring

修改時間。

statusstring

重要僅Qwen-Audio-TTS/CosyVoice返回。

音色狀態，取值參見"音色狀態說明"。

target_modelstring

重要僅Qwen返回。

驅動音色的語音合成模型。

languagestring

音色語言。

voice_promptstring

聲音描述文本。

preview_textstring

預覽音頻文本。

usageobject

本次請求用量資訊。

屬性

count integer

Qwen-Audio-TTS/CosyVoice固定為1。Qwen固定為0。

Qwen-Audio-TTS/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"
}

重要Qwen-Audio-TTS/CosyVoice返回voice_list數組，每項包含voice_id欄位；Qwen同樣返回voice_list數組，每項包含voice欄位。Qwen的output中還包含page_index、page_size和total_count分頁資訊欄位。

查詢音色詳情

請求體

modelstring（必選）

聲音設計模型。取值：

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

inputobject（必選）

輸入參數對象。

屬性

action string（必選）

操作類型。Qwen-Audio-TTS/CosyVoice：query_voice。Qwen聲音設計：query。

voice_id string（條件必選）

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

要查詢的音色ID。

voice string（條件必選）

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

要查詢的音色名稱。

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"
    }
}'

Qwen聲音設計

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

返回體

request_idstring

本次調用的唯一識別碼。

outputobject

模型返回的資料。

屬性

voice_id / voicestring

音色ID。Qwen-Audio-TTS/CosyVoice聲音設計返回voice_id，Qwen聲音設計返回voice。

gmt_createstring

建立時間。

gmt_modifiedstring

修改時間。

statusstring

重要僅Qwen-Audio-TTS/CosyVoice返回。

音色狀態，取值參見"音色狀態說明"。

target_modelstring

驅動音色的語音合成模型。

languagestring

重要僅Qwen聲音設計返回。

音色語言。

voice_promptstring

重要僅Qwen-Audio-TTS/CosyVoice聲音設計返回。

聲音描述文本。

preview_textstring

重要僅Qwen-Audio-TTS/CosyVoice聲音設計返回。

預覽音頻文本。

usageobject

本次請求用量資訊。

屬性

count integer

固定為1。

Qwen-Audio-TTS/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"
}

重要Qwen-Audio-TTS/CosyVoice聲音設計返回voice_id、voice_prompt等欄位。Qwen聲音設計返回voice和language欄位。

刪除音色

請求體

modelstring（必選）

聲音設計模型。取值：

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

inputobject（必選）

輸入參數對象。

屬性

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

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聲音設計

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

返回體

request_idstring

本次調用的唯一識別碼。

outputobject

模型返回的資料。Qwen-Audio-TTS/CosyVoice返回Null 物件，Qwen返回已刪除的音色名稱。

屬性

voicestring

重要僅Qwen返回。

已刪除的音色名稱。

usageobject

本次請求用量資訊。

屬性

count integer

固定為1。

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欄位。

音色狀態說明

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

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