跳转到主要内容
音色设计

音色设计 API 参考

本文介绍声音设计的HTTP API接口详情,包括创建音色、查询音色列表、查询音色详情和删除音色四个操作。

用户指南:声音设计。
Qwen声音设计已下线,请使用声音设计功能。

接口地址

POST https://maas.qianwenaiapi.com/api/v1/services/audio/tts/customization

请求头

参数类型是否必选说明
Authorizationstring是鉴权令牌,格式为Bearer $DASHSCOPE_API_KEY,使用时,将"$DASHSCOPE_API_KEY"替换为实际的API Key。
Content-Typestring是请求体的媒体类型。固定为application/json。

创建音色

请求体

curl -X POST https://maas.qianwenaiapi.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"
    }
}'
参数类型说明
modelstring(必选) 声音设计模型。固定为voice-enrollment(Qwen-Audio-TTS/CosyVoice声音设计)。
inputobject(必选) 输入参数对象。
input.actionstring(必选) 操作类型。固定为create_voice。
input.target_modelstring(必选) 驱动音色的语音合成模型。必须与后续调用语音合成接口时使用的模型一致,否则合成会失败。
input.voice_promptstring(必选) 声音描述文本,仅支持中文和英文,最大长度500字符。
input.preview_textstring(必选) 预览音频对应的文本。最小长度15字符,最大长度200字符,支持中文和英文。
input.prefixstring(条件必选) 音色名称前缀,仅允许数字和英文字母,不超过10个字符。生成的音色名格式:{target_model}-vd-{prefix}-{唯一标识}
input.language_hintsarray[string](可选) 指定生成音色的语言倾向,影响音色的语言特征和发音倾向,建议根据实际使用场景选择对应语言代码。若使用该参数,设置的语种须与 preview_text 的语种一致。 此参数为数组,但当前版本仅处理第一个元素。 取值范围:
  • zh:中文
  • en:英文
默认值:["zh"]。
parametersobject(可选) 声音设计的参数配置。
parameters.sample_rateint(可选) 预览音频采样率(Hz)。支持:16000、24000、48000。 默认值:24000。
parameters.response_formatstring(可选) 预览音频格式。支持:pcm、wav、mp3。 默认值:wav。

返回体

{
    "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"
}
参数类型说明
request_idstring本次调用的唯一标识符。
outputobject模型返回的数据。
output.voice_idstring音色ID。可直接用于语音合成接口的voice参数。
output.preview_audioobject预览音频数据。
output.preview_audio.datastring预览音频数据,Base64编码。
output.preview_audio.sample_rateint预览音频采样率(Hz)。
output.preview_audio.response_formatstring预览音频格式。
output.target_modelstring驱动音色的语音合成模型。
usageobject本次请求用量信息。
usage.countinteger创建的音色数量,固定为1。

查询音色列表

请求体

curl -X POST https://maas.qianwenaiapi.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
    }
}'
参数类型说明
modelstring(必选) 声音设计模型。固定为voice-enrollment(Qwen-Audio-TTS/CosyVoice声音设计)。
inputobject(必选) 输入参数对象。
input.actionstring(必选) 操作类型。固定为list_voice。
input.prefixstring(可选) 按前缀筛选音色。
input.page_indexinteger(可选) 页码索引。
input.page_sizeinteger(可选) 每页包含数据条数。

返回体

{
    "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"
}
参数类型说明
request_idstring本次调用的唯一标识符。
outputobject模型返回的数据。
output.voice_listarray[object]查询到的音色列表。
output.voice_list.voice_idstring音色ID。
output.voice_list.gmt_createstring创建时间。
output.voice_list.gmt_modifiedstring修改时间。
output.voice_list.statusstring音色状态,取值参见"音色状态说明"。
output.voice_list.voice_promptstring声音描述文本。
output.voice_list.preview_textstring预览音频文本。
usageobject本次请求用量信息。
usage.countinteger固定为1。

查询音色详情

请求体

curl -X POST https://maas.qianwenaiapi.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"
    }
}'
参数类型说明
modelstring(必选) 声音设计模型。固定为voice-enrollment(Qwen-Audio-TTS/CosyVoice声音设计)。
inputobject(必选) 输入参数对象。
input.actionstring(必选) 操作类型。固定为query_voice。
input.voice_idstring(条件必选) 要查询的音色ID。

返回体

{
    "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": {},
    "request_id": "xxxx-xxxx-xxxx"
}
参数类型说明
request_idstring本次调用的唯一标识符。
outputobject模型返回的数据。
output.voice_idstring音色ID。
output.gmt_createstring创建时间。
output.gmt_modifiedstring修改时间。
output.statusstring音色状态,取值参见"音色状态说明"。
output.target_modelstring驱动音色的语音合成模型。
output.voice_promptstring声音描述文本。
output.preview_textstring预览音频文本。
usageobject本次请求用量信息。
usage.countinteger固定为1。

删除音色

请求体

curl -X POST https://maas.qianwenaiapi.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"
    }
}'
参数类型说明
modelstring(必选) 声音设计模型。固定为voice-enrollment(Qwen-Audio-TTS/CosyVoice声音设计)。
inputobject(必选) 输入参数对象。
input.actionstring(必选) 操作类型。固定为delete_voice。
input.voice_idstring(条件必选) 要删除的音色ID。

返回体

{
    "output": {},
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
参数类型说明
request_idstring本次调用的唯一标识符。
outputobject模型返回的数据,返回空对象。
usageobject本次请求用量信息。
usage.countinteger固定为1。

音色状态说明

音色创建后会经过审核流程,以下是各状态的含义。
状态说明
DEPLOYING审核中/处理中。
OK审核通过,可正常使用。
UNDEPLOYED审核未通过,不可使用。