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（必选）驱动音色的目标模型。必须与后续使用该音色的模型一致，否则调用失败。url string（必选）用于复刻音色的音频文件URL，要求公网可访问。prefix string（必选）音色名称前缀，仅允许数字和英文字母，不超过10个字符。生成的音色名格式：{target_model}-{prefix}-{唯一标识}。language_hints array[string]（可选）辅助模型识别样本音频的语种，从而更准确地提取音色特征，提升复刻效果。若设置的语种与实际音频语种不符（例如为中文音频设置 en），系统将忽略该设置并自动检测语种。此参数为数组，长度必须为 1。
适用于 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-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-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-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",
        "url": "https://your-audio-url.wav",
        "language_hints": ["zh"],
        "enable_volume_normalization": "false"
    }
}'

返回体

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。url string（必选）新的音频文件URL，要求公网可访问。
以下为新加坡地域的配置，调用时请将"{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"
    }
}'

返回体

request_idstring本次调用的唯一标识符。outputobject模型返回的数据，更新操作返回空对象。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审核未通过，不可使用。
使用 API
文本生成
图像生成
视频生成
世界模型
音频
实时多模态
Realtime API
  • 概述
向量与排序
决策模型
更多模型
工具包/框架
TokenPlan
模型生产
文件管理
账单
模型管理
更多