声音复刻HTTP API参考 - 大模型服务平台百炼

本文介绍声音复刻的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	是	请求体的媒体类型。CosyVoice/Qwen-TTS固定为`application/json`，MiniMax固定为`application/json; charset=utf-8`。

创建音色

请求体	以下为新加坡地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。 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-plus", "prefix": "myvoice", "url": "https://your-audio-url.wav", "language_hints": ["zh"] } }'` 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-enrollment", "input": { "action": "create", "target_model": "qwen3-tts-vc-realtime-2026-01-15", "preferred_name": "myvoice", "audio": {"data": "data:audio/mpeg;base64,{base64_encoded_audio}"} } }'`
model `string` （必选）声音复刻模型。取值： `voice-enrollment`：CosyVoice声音复刻。 `qwen-voice-enrollment`：Qwen声音复刻。
input `object` （必选）输入参数对象。属性 action `string` （必选）操作类型。 CosyVoice（`voice-enrollment`）：固定为`create_voice`。 Qwen（`qwen-voice-enrollment`）：固定为`create`。 target_model `string` （必选）驱动音色的语音合成模型。必须与后续调用语音合成接口时使用的模型一致，否则合成会失败。 url `string` （条件必选）重要仅适用于CosyVoice声音复刻（model为`voice-enrollment`时）。用于复刻音色的音频文件URL，要求公网可访问。 audio `object` （条件必选）重要仅适用于Qwen声音复刻（model为`qwen-voice-enrollment`时）。音频数据，支持两种提交方式： Data URL（Base64编码）：格式为`{"data": "data:{mime_type};base64,{base64_encoded_data}"}`，支持的MIME类型：`audio/wav`、`audio/mpeg`、`audio/mp4`。音频URL：格式为`{"data": "https://your-audio-url.wav"}`，URL必须公网可访问且无需鉴权。 text `string` （可选）重要仅适用于Qwen声音复刻（model为`qwen-voice-enrollment`时）。音频对应的文本内容，用于辅助提升复刻效果。 prefix `string` （条件必选）重要仅适用于CosyVoice（model为`voice-enrollment`时）。音色名称前缀，仅允许数字和英文字母，不超过10个字符。生成的音色名格式：`{target_model}-{prefix}-{唯一标识}`。 preferred_name `string` （条件必选）重要仅适用于Qwen声音复刻（model为`qwen-voice-enrollment`时）。音色名称前缀，仅允许数字、英文字母和下划线，不超过16个字符。 language_hints `array[string]` （可选）重要仅适用于CosyVoice声音复刻（model为`voice-enrollment`时），且仅cosyvoice-v3.5-plus、v3.5-flash、v3-plus和v3-flash模型支持。辅助模型识别样本音频的语种，从而更准确地提取音色特征，提升复刻效果。若设置的语种与实际音频语种不符（例如为中文音频设置 `en`），系统将忽略该设置并自动检测语种。此参数为数组，但当前版本仅处理第一个元素。取值范围（因模型而异）： 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"]。 language `string` （可选）重要仅适用于Qwen声音复刻（model为`qwen-voice-enrollment`时）。指定 `audio.data` 音频对应的语种。若使用该参数，设置的语种须与实际用于复刻的音频语种一致。取值范围： zh：中文 en：英文 de：德语 it：意大利语 pt：葡萄牙语 es：西班牙语 ja：日语 ko：韩语 fr：法语 ru：俄语默认值：zh。 max_prompt_audio_length `float` （可选）重要仅适用于CosyVoice声音复刻（model为`voice-enrollment`时），且仅cosyvoice-v3.5-plus、v3.5-flash和v3-flash模型支持。音频预处理后用于声音复刻的参考音频最大时长（秒）。取值范围：[3.0, 30.0]。时间越长效果越好。默认值：10.0。 enable_preprocess `boolean` （可选）重要仅适用于CosyVoice声音复刻（model为`voice-enrollment`时），且仅cosyvoice-v3.5-plus、v3.5-flash和v3-flash模型支持。是否开启音频预处理（降噪、音频增强、音量规整）。有背景噪音时建议开启；安静环境建议关闭以最大程度还原音色。默认值：false。

返回体	CosyVoice声音复刻 `{ "output": { "voice_id": "cosyvoice-v3.5-plus-myvoice-xxxxxx" }, "usage": { "count": 1 }, "request_id": "xxxx-xxxx-xxxx" }` Qwen声音复刻 `{ "output": { "voice": "yourVoice", "target_model": "qwen3-tts-vc-realtime-2026-01-15" }, "usage": { "count": 1 }, "request_id": "xxxx-xxxx-xxxx" }` 重要 CosyVoice返回`voice_id`字段，Qwen返回`voice`字段。Qwen声音复刻还可能返回`fallback_mode`和`fallback_reason`字段。
request_id `string` 本次调用的唯一标识符。
output `object` 模型返回的数据。属性 voice_id / voice `string` 音色ID。CosyVoice返回`voice_id`，Qwen返回`voice`。可直接用于语音合成接口的voice参数。 target_model `string` 重要仅Qwen返回。驱动音色的语音合成模型。 fallback_mode `boolean` 重要仅适用于Qwen声音复刻（model为`qwen-voice-enrollment`时）。是否以降级模式创建音色。当音频质量不佳或与文本不匹配时，该值为`true`，表示复刻效果可能不理想。 fallback_reason `string` 重要仅当`fallback_mode`为`true`时返回。降级原因。可能的值包括`no_merged_segments`（无法合并音频片段）、`no_valid_asr_segments`（音频与文本严重不匹配）等。
usage `object` 本次请求用量信息。属性 count `integer` 创建的音色数量，固定为1。

查询音色列表

请求体

以下为新加坡地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。

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

model string （必选）

声音复刻模型。取值：

voice-enrollment：CosyVoice声音复刻。
qwen-voice-enrollment：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-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 `{ "output": { "page_index": 0, "page_size": 10, "total_count": 2, "voice_list": [ { "voice": "yourVoice1", "gmt_create": "2025-08-11 17:59:32", "gmt_modified": "2025-08-11 17:59:32", "language": "zh", "target_model": "qwen3-tts-vc-realtime-2026-01-15" } ] }, "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]` 查询到的音色列表。CosyVoice和Qwen均使用`voice_list`字段名。属性 voice_id / voice `string` 音色ID。CosyVoice为`voice_id`，Qwen为`voice`。 gmt_create `string` 创建时间。 gmt_modified `string` 修改时间。 status `string` 重要仅CosyVoice返回。音色状态，取值参见"音色状态说明"。 target_model `string` 重要仅Qwen返回。驱动音色的语音合成模型。
usage `object` 本次请求用量信息。属性 count `integer` CosyVoice固定为1。Qwen固定为0。

查询音色详情

重要

仅适用于CosyVoice（model为voice-enrollment时）。Qwen模型不支持查询音色详情操作。

请求体

以下为新加坡地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。

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

model string （必选）

固定为voice-enrollment（CosyVoice）。

input object （必选）

输入参数对象。

属性

action string （必选）

固定为query_voice。

voice_id string （必选）

要查询的音色ID。

返回体	`{ "output": { "gmt_create": "2024-12-11 13:38:02", "resource_link": "https://yourAudioFileUrl", "target_model": "cosyvoice-v3.5-plus", "gmt_modified": "2024-12-11 13:38:02", "status": "OK" }, "usage": { "count": 1 }, "request_id": "xxxx-xxxx-xxxx" }`
request_id `string` 本次调用的唯一标识符。
output `object` 模型返回的数据。属性 resource_link `string` 音频文件的URL地址。 gmt_create `string` 创建时间。 gmt_modified `string` 修改时间。 status `string` 音色状态，取值参见"音色状态说明"。 target_model `string` 驱动音色的语音合成模型。
usage `object` 本次请求用量信息。属性 count `integer` 固定为1。

更新音色

重要

仅适用于CosyVoice声音复刻（model为voice-enrollment时）。Qwen模型不支持更新操作。

请求体

以下为新加坡地域的配置，调用时请将"{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",
        "url": "https://new-audio-url.wav"
    }
}'

model string （必选）

固定为voice-enrollment。

input object （必选）

输入参数对象。

属性

action string （必选）

固定为update_voice。

voice_id string （必选）

要更新的音色ID。

url string （必选）

新的音频文件URL，要求公网可访问。

返回体	`{ "output": {}, "usage": { "count": 1 }, "request_id": "xxxx-xxxx-xxxx" }`
request_id `string` 本次调用的唯一标识符。
output `object` 模型返回的数据，更新操作返回空对象。
usage `object` 本次请求用量信息。属性 count `integer` 固定为1。

删除音色

请求体

以下为新加坡地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。

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

model string （必选）

声音复刻模型。取值：

voice-enrollment：CosyVoice声音复刻。
qwen-voice-enrollment：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返回空对象，Qwen返回已删除的音色名称。属性 voice `string` 重要仅Qwen返回。已删除的音色名称。
usage `object` 本次请求用量信息。属性 count `integer` 固定为1。

音色状态说明

音色创建后会经过审核流程，以下是各状态的含义。此状态体系仅适用于CosyVoice（model为voice-enrollment时），Qwen的查询和列表返回中不包含status字段。

状态	说明
DEPLOYING	审核中/处理中。
OK	审核通过，可正常使用。
UNDEPLOYED	审核未通过，不可使用。

服务端点

新加坡

华北2（北京）

请求头

创建音色

请求体

CosyVoice声音复刻

Qwen声音复刻

返回体

CosyVoice声音复刻

Qwen声音复刻

查询音色列表

请求体

CosyVoice

Qwen声音复刻

返回体

CosyVoice

Qwen

查询音色详情

请求体

CosyVoice

返回体

更新音色

请求体

返回体

删除音色

请求体

CosyVoice

Qwen声音复刻

返回体

CosyVoice

Qwen

音色状态说明