本文介绍声音设计的HTTP API接口详情，包括创建音色、查询音色列表、查询音色详情和删除音色四个操作。
用户指南：声音设计。
音色创建后会经过审核流程。以下状态适用于 Qwen-Audio-TTS/CosyVoice（
接口地址
- 华北2（北京）
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization调用时请将{WorkspaceId}替换为真实的Workspace ID。请求头
参数 | 类型 | 是否必选 | 说明 |
|---|---|---|---|
Authorization | string | 是 | 鉴权令牌，格式为 |
Content-Type | string | 是 | 请求体的媒体类型。固定为 |
创建音色
请求体modelstring（必选）声音设计模型。取值：
object（必选）输入参数对象。
属性 action string（必选）操作类型。
string（必选）驱动音色的语音合成模型。必须与后续调用语音合成接口时使用的模型一致，否则合成会失败。voice_prompt string（必选）声音描述文本，仅支持中文和英文。
string（必选）预览音频对应的文本。
string（必选）音色名称前缀，仅允许数字和英文字母，不超过10个字符。生成的音色名格式：{target_model}-vd-{prefix}-{唯一标识}language_hints array[string]（可选）指定生成音色的语言倾向，影响音色的语言特征和发音倾向，建议根据实际使用场景选择对应语言代码。若使用该参数，设置的语种须与 preview_text 的语种一致。此参数为数组，但当前版本仅处理第一个元素。取值范围：
object（可选）声音设计的参数配置。
属性 sample_rate int（可选）预览音频采样率（Hz）。
string（可选）预览音频格式。
| 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。 |
返回体request_idstring本次调用的唯一标识符。outputobject模型返回的数据。
属性 voice_id string音色 ID，可用于语音合成接口的 voice 参数。preview_audioobject预览音频数据。
属性 data string预览音频数据，Base64编码。sample_rate int预览音频采样率（Hz）。response_format string预览音频格式。string驱动音色的语音合成模型。object本次请求用量信息。
属性 count integer创建的音色数量，固定为1。 |
查询音色列表
请求体modelstring（必选）声音设计模型。取值：
object（必选）输入参数对象。
属性 action string（必选）固定为 list_voice。prefix string（可选）按前缀筛选音色。page_index integer（可选）页码索引。page_size integer（可选）每页包含数据条数。 | 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。 |
返回体request_idstring本次调用的唯一标识符。outputobject模型返回的数据。
属性 voice_list array[object]查询到的音色列表。
属性 voice_id string音色 ID，可用于语音合成接口的 voice 参数。gmt_createstring创建时间。gmt_modifiedstring修改时间。statusstring音色状态，取值参见"音色状态说明"。voice_promptstring声音描述文本。preview_textstring预览音频文本。object本次请求用量信息。
属性 count integer固定为 1。 |
查询音色详情
请求体modelstring（必选）声音设计模型。取值：
object（必选）输入参数对象。
属性 action string（必选）固定为 query_voice。voice_id string（必选）要查询的音色ID。 | 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。 |
返回体request_idstring本次调用的唯一标识符。outputobject模型返回的数据。
属性 voice_id string音色 ID，可用于语音合成接口的 voice 参数。gmt_createstring创建时间。gmt_modifiedstring修改时间。statusstring音色状态，取值参见"音色状态说明"。target_modelstring驱动音色的语音合成模型。voice_promptstring声音描述文本。preview_textstring预览音频文本。object本次请求用量信息。
属性 count integer固定为1。 |
删除音色
请求体modelstring（必选）声音设计模型。取值：
object（必选）输入参数对象。
属性 action string（必选）固定为 delete_voice。voice_id string（必选）要删除的音色ID。 | 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。 |
返回体request_idstring本次调用的唯一标识符。outputobject模型返回的数据，为空对象。usageobject本次请求用量信息。
属性 count integer固定为1。 |
音色状态说明
音色创建后会经过审核流程。以下状态适用于 Qwen-Audio-TTS/CosyVoice（model 为 voice-enrollment）。
状态 | 说明 |
|---|---|
DEPLOYING | 审核中/处理中。 |
OK | 审核通过，可正常使用。 |
UNDEPLOYED | 审核未通过，不可使用。 |