全部產品
Search
文件中心

Alibaba Cloud Model Studio:聲音複刻 HTTP API:Qwen-Audio 與 CosyVoice

更新時間:Nov 18, 2026

Qwen-Audio、CosyVoice 聲音複刻的 HTTP 介面參數、傳回欄位和呼叫示例。

本文適用於 Qwen-Audio-TTS、Qwen-Audio-Realtime、CosyVoice。

先獲取 API Key並配置環境變量。請求示例讀取 DASHSCOPE_API_KEY。使用不同 API 管理同一音色時,請使用同一賬號。

SDK 定義另見 Java SDK 和 Python SDK。

介面地址

華北2(北京)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization

新加坡

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization

將 {WorkspaceId} 替換為真實的Workspace ID,可在百鍊控制台的业务空间详情頁面查看。北京和新加坡的 API Key 不同。

重要阿里雲百鍊為華北2(北京)、新加坡地域推出了業務空間專屬域名,能夠為推理請求提供卓越的性能和更高的穩定性,建議遷移至新域名:

  • 華北2(北京)地域:從 dashscope.aliyuncs.com 遷移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com。
  • 新加坡地域:從 dashscope-intl.aliyuncs.com 遷移至 {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com。

現有域名仍可正常使用。

請求頭

參數類型是否必選說明

Authorization

string

是

鑒權令牌,格式為Bearer <your_api_key>,使用時,將"<your_api_key>"替換為實際的API Key。

Content-Type

string

是

固定為 application/json。

音訊要求與費用

參考音訊要求見聲音複刻用戶指南。Qwen-Audio-Realtime 的複刻流程見即時語音對話音色複刻。Qwen-Audio-Realtime 建立音色免費,模型呼叫按目標模型計費,詳情見計費說明,數量限制見配額說明。

請求體

model string — 必選

固定為 voice-enrollment。

input object — 必選

屬性

action string — 必選

操作類型:

  • create_voice: 建立音色。
  • list_voice: 查詢音色列表。
  • query_voice: 查詢音色詳情。
  • update_voice: 更新音色。
  • delete_voice: 刪除音色。

target_model string — 建立時必選

後續使用音色的目標模型。必須與後續呼叫時使用的模型一致,否則呼叫失敗。

目標模型可選擇支援聲音複刻的 Qwen-Audio-TTS、Qwen-Audio-Realtime 或 CosyVoice 型號,具體模型與地域見支援模型。

audio string — 建立或更新時,未傳 url 則必選

建立時提供參考音訊,更新時提供新的參考音訊。支援公網可存取的 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.1-realtime-flash、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.1-realtime-flash、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.1-realtime-flash、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.1-realtime-flash、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"。

page_index integer — 查詢列表時可選

頁碼索引。

page_size integer — 查詢列表時可選

每頁包含資料條數。

voice_id string — 查詢詳情、更新或刪除時必選

要查詢、更新或刪除的音色 ID。

請求示例

建立

示例使用 qwen-audio-3.1-tts-plus,請將 input 中的 target_model 替換為實際目標模型 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": "create_voice",
        "target_model": "qwen-audio-3.1-tts-plus",
        "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")

查詢列表

以下為新加坡地域的配置,呼叫時請將"{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
    }
}'

查詢詳情

以下為新加坡地域的配置,呼叫時請將"{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"
    }
}'

更新

以下為新加坡地域的配置,呼叫時請將"{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"
    }
}'

刪除

以下為新加坡地域的配置,呼叫時請將"{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_id string

本次呼叫的唯一標識符。

output object

建立、查詢列表或查詢詳情時傳回相應欄位;更新或刪除時傳回空物件。

屬性

voice_id string — 建立時傳回

音色 ID。

voice_list array[object] — 查詢列表時傳回

查詢到的音色列表。

屬性

voice_id string

音色 ID。

target_model string

驅動音色的目標模型(語音合成或即時語音對話)。

gmt_create string

建立時間。

gmt_modified string

修改時間。

status string

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

resource_link string — 查詢詳情時傳回

音訊文件的URL地址。

gmt_create string — 查詢詳情時傳回

建立時間。

gmt_modified string — 查詢詳情時傳回

修改時間。

status string — 查詢詳情時傳回

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

target_model string — 查詢詳情時傳回

驅動音色的目標模型(語音合成或即時語音對話)。

usage object

本次請求用量資訊。

屬性

count integer

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

響應示例

建立

{
    "output": {
        "voice_id": "qwen-audio-3.1-tts-plus-myvoice-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

查詢列表

{
    "output": {
        "voice_list": [
            {
                "voice_id": "qwen-audio-3.0-tts-flash-myvoice-xxxxxx",
                "target_model": "qwen-audio-3.0-tts-flash",
                "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"
}

查詢詳情

{
    "output": {
        "gmt_create": "2024-12-11 13:38:02",
        "resource_link": "https://yourAudioFileUrl",
        "target_model": "qwen-audio-3.1-tts-plus",
        "gmt_modified": "2024-12-11 13:38:02",
        "status": "OK"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

更新

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

刪除

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

音色狀態說明

音色建立後會經過審核流程。

狀態說明

DEPLOYING

審核中/處理中。

OK

審核透過,可正常使用。

UNDEPLOYED

審核未透過,不可使用。

錯誤資訊

如遇報錯問題,請參見錯誤碼進行排查。