Skip to main content

聲音複刻HTTP API參考

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

介面地址

Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice

  • 新加坡
  • 華北2（北京）
POST https://{WorkspaceId}.ap-southeast-1.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

要求標頭

參數類型是否必選說明
Authorizationstring是鑒權令牌，格式為Bearer <your_api_key>，使用時，將"<your_api_key>"替換為實際的API Key。
Content-Typestring是請求體的媒體類型。依模型系列設定：
  • Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice：application/json。

建立音色

Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice

請求體

modelstring（必選）固定為 voice-enrollment。inputobject（必選）輸入參數對象。

屬性

action string（必選）固定為 create_voice。target_model string（必選）驅動音色的目標模型。必須與後續使用該音色的模型一致，否則呼叫失敗。audio string（必選）用於複刻音色的參考音訊，支援可公開存取的 URL 或 Base64 Data URI，例如 data:audio/wav;base64,...。
相容舊參數 url；使用 url 時可不傳入 audio。url 將逐步棄用，建議改用 audio。
prefix string（必選）音色名稱首碼，僅允許數字和英文字母，不超過10個字元。產生的音色名格式：{target_model}-{prefix}-{唯一標識}。language_hints array[string]（可選）輔助模型識別樣本音訊語種，從而更準確地提取音色特徵，提升複刻效果。若設定的語種與實際音頻語種不符（例如為中文音頻設定 en），系統將忽略該設定並自動檢測語種。此參數為陣列，長度必須為 1。
適用於 qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash、cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-plus、cosyvoice-v3-flash。
  • qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash：
    • zh：中文
    • en：英語
    • fr：法語
    • de：德語
    • ja：日語
    • ko：韓語
    • ru：俄語
    • pt：葡萄牙語
    • th：泰語
    • id：印尼語
    • vi：越南語
    • it：意大利語
    • es：西班牙語
    • ms：馬來西亞語
    • fil：菲律賓語
    • ar：阿拉伯語
  • 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"]。max_prompt_audio_length float（可選）音頻預先處理後用於聲音複刻的參考音頻最大時間長度（秒）。取值範圍：[3.0, 30.0]。預設值：10.0。
適用於 qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash、cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash。
enable_preprocess boolean（可選）是否開啟音頻預先處理（降噪、音頻增強、音量規整）。有背景雜音時建議開啟；安靜環境建議關閉以最大程度還原音色。預設值：false。
適用於 qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash、cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash。
enable_volume_normalization string（可選）是否對用於聲音複刻的樣本音頻進行音量歸一化。取值：
  • "true"：開啟音量歸一化。
  • "false"：關閉音量歸一化。
開啟後，使用所建立音色合成的音頻，其音量可能與關閉該參數時建立的音色不同。預設值："false"。
以下為新加坡地區的配置，調用時請將"{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": "create_voice",
        "target_model": "qwen-audio-3.0-tts-flash",
        "prefix": "myvoice",
        "audio": "https://your-audio-url.wav",
        "language_hints": ["zh"],
        "enable_volume_normalization": "false"
    }
}'
使用本機 WAV 音訊時，可透過以下程式碼產生 Base64 Data URI，並將 audio 的值填入建立或更新請求的 input.audio 欄位。將 sample.wav 替換為本機音訊路徑。
import base64
from pathlib import Path

audio = "data:audio/wav;base64," + base64.b64encode(
    Path("sample.wav").read_bytes()
).decode("ascii")

返回體

request_idstring本次調用的唯一識別碼。outputobject模型返回的資料。

屬性

voice_idstring音色 ID，可用於語音合成介面的 voice 參數。
usageobject本次請求用量資訊。

屬性

count integer建立的音色數量，固定為1。
{
    "output": {
        "voice_id": "qwen-audio-3.0-tts-flash-myvoice-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

查詢音色列表

適用於 Qwen-Audio-TTS、Qwen-Audio-Realtime 和 CosyVoice。

請求體

modelstring（必選）固定為 voice-enrollment。inputobject（必選）輸入參數對象。

屬性

action string（必選）固定為 list_voice。prefix string（可選）按首碼篩選音色。page_index integer（可選）頁碼索引。page_size integer（可選）每頁包含資料條數。
以下為新加坡地區的配置，調用時請將"{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": "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音色狀態，取值參見"音色狀態說明"。
usageobject本次請求用量資訊。

屬性

count integer固定為 1。
{
    "output": {
        "voice_list": [
            {
                "voice_id": "qwen-audio-3.0-tts-flash-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-Audio-TTS、Qwen-Audio-Realtime 和 CosyVoice。

請求體

modelstring（必選）固定為 voice-enrollment。inputobject（必選）輸入參數對象。

屬性

action string（必選）固定為query_voice。voice_id string（必選）要查詢的音色ID。
以下為新加坡地區的配置，調用時請將"{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": "query_voice",
        "voice_id": "yourVoiceId"
    }
}'

返回體

request_idstring本次調用的唯一識別碼。outputobject模型返回的資料。

屬性

resource_linkstring音頻檔案的URL地址。gmt_createstring建立時間。gmt_modifiedstring修改時間。statusstring音色狀態，取值參見"音色狀態說明"。target_modelstring驅動音色的語音合成模型。
usageobject本次請求用量資訊。

屬性

count integer固定為1。
{
    "output": {
        "gmt_create": "2024-12-11 13:38:02",
        "resource_link": "https://yourAudioFileUrl",
        "target_model": "qwen-audio-3.0-tts-flash",
        "gmt_modified": "2024-12-11 13:38:02",
        "status": "OK"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

更新音色

適用於 Qwen-Audio-TTS、Qwen-Audio-Realtime 和 CosyVoice。

請求體

modelstring（必選）固定為 voice-enrollment。inputobject（必選）輸入參數對象。

屬性

action string（必選）固定為update_voice。voice_id string（必選）要更新的音色ID。audio string（必選）新的參考音訊，支援可公開存取的 URL 或 Base64 Data URI，例如 data:audio/wav;base64,...。
相容舊參數 url；使用 url 時可不傳入 audio。url 將逐步棄用，建議改用 audio。
以下為新加坡地區的配置，調用時請將"{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",
        "audio": "https://new-audio-url.wav"
    }
}'

返回體

request_idstring本次調用的唯一識別碼。outputobject模型返回的資料，更新操作返回Null 物件。usageobject本次請求用量資訊。

屬性

count integer固定為1。
{
    "output": {},
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

刪除音色

適用於 Qwen-Audio-TTS、Qwen-Audio-Realtime 和 CosyVoice。

請求體

modelstring（必選）固定為 voice-enrollment。inputobject（必選）輸入參數對象。

屬性

action string（必選）固定為 delete_voice。voice_id string（必選）要刪除的音色ID。
以下為新加坡地區的配置，調用時請將"{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": "delete_voice",
        "voice_id": "yourVoiceId"
    }
}'

返回體

request_idstring本次調用的唯一識別碼。outputobject模型返回的資料，為空物件。usageobject本次請求用量資訊。

屬性

count integer固定為1。
{
    "output": {},
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

音色狀態說明

音色建立後會經過審核流程。以下狀態適用於 Qwen-Audio-TTS、Qwen-Audio-Realtime 和 CosyVoice。
狀態說明
DEPLOYING審核中/處理中。
OK審核通過，可正常使用。
UNDEPLOYED審核未通過，不可使用。