全部產品
Search
文件中心

Alibaba Cloud Model Studio:音色設計 API 參考

更新時間:Nov 06, 2026

本文介紹聲音設計的HTTP API介面詳情,包括建立音色、查詢音色列表、查詢音色詳情和刪除音色四個操作。

使用者指南:聲音設計。

介面地址

華北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

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

inputobject(必選)

輸入參數對象。

屬性

action string(必選)

操作類型。

  • Qwen-Audio-TTS/CosyVoice(voice-enrollment):固定為create_voice。

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字元。

preview_text string(必選)

預覽音頻對應的文本。

  • Qwen-Audio-TTS/CosyVoice(voice-enrollment):最小長度15字元,最大長度200字元,支援中文和英文。

prefix string(必選)

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

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

language_hints array[string](可選)

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

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

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

取值範圍:

  • zh:中文
  • en:英文

預設值:["zh"]。

parametersobject(可選)

聲音設計的參數配置。

屬性

sample_rate int(可選)

預覽音頻採樣率(Hz)。

  • Qwen-Audio-TTS/CosyVoice支援:16000、24000、48000。

預設值:24000。

response_format string(可選)

預覽音頻格式。

  • Qwen-Audio-TTS/CosyVoice支援:pcm、wav、mp3。

預設值:wav。

以下範例使用華北2(北京)地區的設定,呼叫時請將 {WorkspaceId} 替換為真實的業務空間 ID。

curl -X POST https://{WorkspaceId}.cn-beijing.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"
    }
}'

返回體

request_idstring

本次調用的唯一識別碼。

outputobject

模型返回的資料。

屬性

voice_idstring

音色 ID,可用於語音合成介面的 voice 參數。

preview_audioobject

預覽音頻資料。

屬性

data string

預覽音頻資料,Base64編碼。

sample_rate int

預覽音頻採樣率(Hz)。

response_format string

預覽音頻格式。

target_modelstring

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

usageobject

本次請求用量資訊。

屬性

count integer

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

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

查詢音色列表

請求體

modelstring(必選)

聲音設計模型。取值:

  • voice-enrollment:Qwen-Audio-TTS/CosyVoice聲音設計。

inputobject(必選)

輸入參數對象。

屬性

action string(必選)

固定為 list_voice。

prefix string(可選)

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

按首碼篩選音色。

page_index integer(可選)

頁碼索引。

page_size integer(可選)

每頁包含資料條數。

以下範例使用華北2(北京)地區的設定,呼叫時請將 {WorkspaceId} 替換為真實的業務空間 ID。

curl -X POST https://{WorkspaceId}.cn-beijing.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
    }
}'

返回體

request_idstring

本次調用的唯一識別碼。

outputobject

模型返回的資料。

屬性

voice_listarray[object]

查詢到的音色列表。

屬性

voice_idstring

音色 ID,可用於語音合成介面的 voice 參數。

gmt_createstring

建立時間。

gmt_modifiedstring

修改時間。

statusstring

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

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

voice_promptstring

聲音描述文本。

preview_textstring

預覽音頻文本。

usageobject

本次請求用量資訊。

屬性

count integer

固定為 1。

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

查詢音色詳情

請求體

modelstring(必選)

聲音設計模型。取值:

  • voice-enrollment:Qwen-Audio-TTS/CosyVoice聲音設計。

inputobject(必選)

輸入參數對象。

屬性

action string(必選)

固定為 query_voice。

voice_id string(必選)

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

要查詢的音色ID。

以下範例使用華北2(北京)地區的設定,呼叫時請將 {WorkspaceId} 替換為真實的業務空間 ID。

curl -X POST https://{WorkspaceId}.cn-beijing.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"
    }
}'

返回體

request_idstring

本次調用的唯一識別碼。

outputobject

模型返回的資料。

屬性

voice_idstring

音色 ID,可用於語音合成介面的 voice 參數。

gmt_createstring

建立時間。

gmt_modifiedstring

修改時間。

statusstring

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

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

target_modelstring

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

voice_promptstring

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

聲音描述文本。

preview_textstring

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

預覽音頻文本。

usageobject

本次請求用量資訊。

屬性

count integer

固定為1。

{
    "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": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

刪除音色

請求體

modelstring(必選)

聲音設計模型。取值:

  • voice-enrollment:Qwen-Audio-TTS/CosyVoice聲音設計。

inputobject(必選)

輸入參數對象。

屬性

action string(必選)

固定為 delete_voice。

voice_id string(必選)

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

要刪除的音色ID。

以下範例使用華北2(北京)地區的設定,呼叫時請將 {WorkspaceId} 替換為真實的業務空間 ID。

curl -X POST https://{WorkspaceId}.cn-beijing.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"
    }
}'

返回體

request_idstring

本次調用的唯一識別碼。

outputobject

模型返回的資料,為空物件。

usageobject

本次請求用量資訊。

屬性

count integer

固定為1。

{
    "output": {},
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

音色狀態說明

音色建立後會經過審核流程。以下狀態適用於 Qwen-Audio-TTS/CosyVoice(model 為 voice-enrollment)。

狀態

說明

DEPLOYING

審核中/處理中。

OK

審核通過,可正常使用。

UNDEPLOYED

審核未通過,不可使用。