AI 助理
文档备案控制台
官方文档
首页

声音设计API参考

更新时间：
复制 MD 格式
产品详情
我的收藏

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

用户指南：声音设计。

服务端点

华北2（北京）

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

调用时请将{WorkspaceId}替换为真实的Workspace ID。

新加坡

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

{WorkspaceId}需要替换为真实的Workspace ID。现有域名仍可正常使用。

请求头

参数

类型

是否必选

说明

Authorization

string

是

鉴权令牌，格式为Bearer <your_api_key>，使用时，将"<your_api_key>"替换为实际的API Key。

Content-Type

string

是

请求体的媒体类型。固定为application/json。

创建音色

请求体

以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。

CosyVoice声音设计

curl -X POST https://{WorkspaceId}.cn-beijing.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.5-plus",
        "voice_prompt": "沉稳的中年男性，音色低沉浑厚",
        "preview_text": "各位听众朋友，大家好",
        "prefix": "announcer",
        "language_hints": ["zh"]
    },
    "parameters": {
        "sample_rate": 24000,
        "response_format": "wav"
    }
}'

Qwen声音设计

curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-design",
    "input": {
        "action": "create",
        "target_model": "qwen3-tts-vd-realtime-2026-01-15",
        "preferred_name": "announcer",
        "voice_prompt": "沉稳的中年男性，音色低沉浑厚",
        "preview_text": "各位听众朋友，大家好",
        "language": "zh"
    },
    "parameters": {
        "sample_rate": 24000,
        "response_format": "wav"
    }
}'

model string （必选）

声音设计模型。取值：

  • voice-enrollment：CosyVoice声音设计。

  • qwen-voice-design：Qwen声音设计。

input object （必选）

输入参数对象。

属性

action string （必选）

操作类型。

  • CosyVoice（voice-enrollment）：固定为create_voice。

  • Qwen（qwen-voice-design）：固定为create。

target_model string （必选）

驱动音色的语音合成模型。必须与后续调用语音合成接口时使用的模型一致，否则合成会失败。

voice_prompt string （必选）

声音描述文本，仅支持中文和英文。

  • CosyVoice（voice-enrollment）：最大长度500字符。

  • Qwen（qwen-voice-design）：最大长度2048字符。

preview_text string （必选）

预览音频对应的文本。

  • CosyVoice（voice-enrollment）：最大长度200字符，支持中文和英文。

  • Qwen（qwen-voice-design）：最大长度1024字符，支持中文、英文、德语、意大利语、葡萄牙语、西班牙语、日语、韩语、法语、俄语。

prefix string （条件必选）

重要

仅适用于CosyVoice（model为voice-enrollment时）。

音色名称前缀，仅允许数字和英文字母，不超过10个字符。生成的音色名格式：{target_model}-vd-{prefix}-{唯一标识}

preferred_name string （条件必选）

重要

仅适用于Qwen（model为qwen-voice-design时）。

音色名称前缀，仅允许数字、英文字母和下划线，不超过16个字符。

language_hints array[string] （可选）

重要

仅适用于CosyVoice（model为voice-enrollment时）。

指定生成音色的语言倾向，影响音色的语言特征和发音倾向，建议根据实际使用场景选择对应语言代码。若使用该参数，设置的语种须与 preview_text 的语种一致。

此参数为数组，但当前版本仅处理第一个元素。

取值范围：

  • zh：中文

  • en：英文

默认值：["zh"]。

language string （可选）

重要

仅适用于Qwen（model为qwen-voice-design时）。

指定生成音色的语言倾向，影响音色的语言特征和发音倾向，建议根据实际使用场景选择对应语言代码。若使用该参数，设置的语种须与 preview_text 的语种一致。

取值范围：

  • zh：中文

  • en：英文

  • de：德语

  • it：意大利语

  • pt：葡萄牙语

  • es：西班牙语

  • ja：日语

  • ko：韩语

  • fr：法语

  • ru：俄语

默认值：zh。

parameters object （可选）

声音设计的参数配置。

属性

sample_rate int （可选）

预览音频采样率（Hz）。

  • CosyVoice支持：16000、24000、48000。

  • Qwen支持：8000、16000、24000、48000。

默认值：24000。

response_format string （可选）

预览音频格式。

  • CosyVoice支持：pcm、wav、mp3。

  • Qwen支持：pcm、wav、mp3、opus。

默认值：wav。

返回体

CosyVoice声音设计

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

Qwen声音设计

{
    "output": {
        "preview_audio": {
            "data": "{base64_encoded_audio}",
            "sample_rate": 24000,
            "response_format": "wav"
        },
        "target_model": "qwen3-tts-vd-realtime-2026-01-15",
        "voice": "yourVoice"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
重要

CosyVoice返回voice_id字段，Qwen返回voice字段。

request_id string

本次调用的唯一标识符。

output object

模型返回的数据。

属性

voice_id / voice string

音色ID。CosyVoice返回voice_id，Qwen返回voice。可直接用于语音合成接口的voice参数。

preview_audio object

预览音频数据。

属性

data string

预览音频数据，Base64编码。

sample_rate int

预览音频采样率（Hz）。

response_format string

预览音频格式。

target_model string

驱动音色的语音合成模型。

usage object

本次请求用量信息。

属性

count integer

创建的音色数量，固定为1。

查询音色列表

请求体

以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。

CosyVoice

curl -X POST https://{WorkspaceId}.cn-beijing.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}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-design",
    "input": {
        "action": "list",
        "page_size": 10,
        "page_index": 0
    }
}'

model string （必选）

声音设计模型。取值：

  • voice-enrollment：CosyVoice声音设计。

  • qwen-voice-design：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-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"
}

Qwen

{
    "output": {
        "page_index": 0,
        "page_size": 10,
        "total_count": 1,
        "voice_list": [
            {
                "voice": "yourVoice",
                "gmt_create": "2025-08-11 17:59:32",
                "gmt_modified": "2025-08-11 17:59:32",
                "language": "zh",
                "target_model": "qwen3-tts-vd-realtime-2026-01-15",
                "voice_prompt": "沉稳的中年男性播音员",
                "preview_text": "各位听众朋友们，大家好"
            }
        ]
    },
    "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]

查询到的音色列表。

属性

voice_id / voice string

音色ID。CosyVoice为voice_id，Qwen为voice。

gmt_create string

创建时间。

gmt_modified string

修改时间。

status string

重要

仅CosyVoice返回。

音色状态，取值参见"音色状态说明"。

target_model string

重要

仅Qwen返回。

驱动音色的语音合成模型。

language string

音色语言。

voice_prompt string

声音描述文本。

preview_text string

预览音频文本。

usage object

本次请求用量信息。

属性

count integer

CosyVoice固定为1。Qwen固定为0。

查询音色详情

请求体

以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。

CosyVoice

curl -X POST https://{WorkspaceId}.cn-beijing.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"
    }
}'

Qwen声音设计

curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-design",
    "input": {
        "action": "query",
        "voice": "yourVoice"
    }
}'

model string （必选）

声音设计模型。取值：

  • voice-enrollment：CosyVoice声音设计。

  • qwen-voice-design：Qwen声音设计。

input object （必选）

输入参数对象。

属性

action string （必选）

操作类型。CosyVoice：query_voice。Qwen声音设计：query。

voice_id string （条件必选）

重要

仅适用于CosyVoice。

要查询的音色ID。

voice string （条件必选）

重要

仅适用于Qwen声音设计（model为qwen-voice-design时）。

要查询的音色名称。

返回体

CosyVoice声音设计

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

Qwen声音设计

{
    "output": {
        "voice": "yourVoice",
        "gmt_create": "2025-08-11 17:59:32",
        "gmt_modified": "2025-08-11 17:59:32",
        "language": "zh",
        "target_model": "qwen3-tts-vd-realtime-2026-01-15"
    },
    "usage": {
        "count": 0
    },
    "request_id": "xxxx-xxxx-xxxx"
}
重要

CosyVoice声音设计返回voice_id、voice_prompt等字段。Qwen声音设计返回voice和language字段。

request_id string

本次调用的唯一标识符。

output object

模型返回的数据。

属性

voice_id / voice string

音色ID。CosyVoice声音设计返回voice_id，Qwen声音设计返回voice。

gmt_create string

创建时间。

gmt_modified string

修改时间。

status string

重要

仅CosyVoice返回。

音色状态，取值参见"音色状态说明"。

target_model string

驱动音色的语音合成模型。

language string

重要

仅Qwen声音设计返回。

音色语言。

voice_prompt string

重要

仅CosyVoice声音设计返回。

声音描述文本。

preview_text string

重要

仅CosyVoice声音设计返回。

预览音频文本。

usage object

本次请求用量信息。

属性

count integer

固定为1。

删除音色

请求体

以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。

CosyVoice

curl -X POST https://{WorkspaceId}.cn-beijing.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}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-design",
    "input": {
        "action": "delete",
        "voice": "yourVoice"
    }
}'

model string （必选）

声音设计模型。取值：

  • voice-enrollment：CosyVoice声音设计。

  • qwen-voice-design：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

审核未通过，不可使用。
上一篇：Python SDK参考下一篇：音乐生成