本文介绍声音设计的HTTP API接口详情,包括创建音色、查询音色列表、查询音色详情和删除音色四个操作。
用户指南:声音设计。
音色创建后会经过审核流程,以下是各状态的含义。
Qwen声音设计已下线,请使用声音设计功能。
接口地址
POST https://maas.qianwenaiapi.com/api/v1/services/audio/tts/customization
请求头
| 参数 | 类型 | 是否必选 | 说明 |
|---|---|---|---|
| Authorization | string | 是 | 鉴权令牌,格式为Bearer $DASHSCOPE_API_KEY,使用时,将"$DASHSCOPE_API_KEY"替换为实际的API Key。 |
| Content-Type | string | 是 | 请求体的媒体类型。固定为application/json。 |
创建音色
请求体
| 参数 | 类型 | 说明 |
|---|---|---|
| model | string | (必选) 声音设计模型。固定为voice-enrollment(Qwen-Audio-TTS/CosyVoice声音设计)。 |
| input | object | (必选) 输入参数对象。 |
| input.action | string | (必选) 操作类型。固定为create_voice。 |
| input.target_model | string | (必选) 驱动音色的语音合成模型。必须与后续调用语音合成接口时使用的模型一致,否则合成会失败。 |
| input.voice_prompt | string | (必选) 声音描述文本,仅支持中文和英文,最大长度500字符。 |
| input.preview_text | string | (必选) 预览音频对应的文本。最小长度15字符,最大长度200字符,支持中文和英文。 |
| input.prefix | string | (条件必选) 音色名称前缀,仅允许数字和英文字母,不超过10个字符。生成的音色名格式:{target_model}-vd-{prefix}-{唯一标识} |
| input.language_hints | array[string] | (可选) 指定生成音色的语言倾向,影响音色的语言特征和发音倾向,建议根据实际使用场景选择对应语言代码。若使用该参数,设置的语种须与 preview_text 的语种一致。 此参数为数组,但当前版本仅处理第一个元素。 取值范围:
|
| parameters | object | (可选) 声音设计的参数配置。 |
| parameters.sample_rate | int | (可选) 预览音频采样率(Hz)。支持:16000、24000、48000。 默认值:24000。 |
| parameters.response_format | string | (可选) 预览音频格式。支持:pcm、wav、mp3。 默认值:wav。 |
返回体
| 参数 | 类型 | 说明 |
|---|---|---|
| request_id | string | 本次调用的唯一标识符。 |
| output | object | 模型返回的数据。 |
| output.voice_id | string | 音色ID。可直接用于语音合成接口的voice参数。 |
| output.preview_audio | object | 预览音频数据。 |
| output.preview_audio.data | string | 预览音频数据,Base64编码。 |
| output.preview_audio.sample_rate | int | 预览音频采样率(Hz)。 |
| output.preview_audio.response_format | string | 预览音频格式。 |
| output.target_model | string | 驱动音色的语音合成模型。 |
| usage | object | 本次请求用量信息。 |
| usage.count | integer | 创建的音色数量,固定为1。 |
查询音色列表
请求体
| 参数 | 类型 | 说明 |
|---|---|---|
| model | string | (必选) 声音设计模型。固定为voice-enrollment(Qwen-Audio-TTS/CosyVoice声音设计)。 |
| input | object | (必选) 输入参数对象。 |
| input.action | string | (必选) 操作类型。固定为list_voice。 |
| input.prefix | string | (可选) 按前缀筛选音色。 |
| input.page_index | integer | (可选) 页码索引。 |
| input.page_size | integer | (可选) 每页包含数据条数。 |
返回体
| 参数 | 类型 | 说明 |
|---|---|---|
| request_id | string | 本次调用的唯一标识符。 |
| output | object | 模型返回的数据。 |
| output.voice_list | array[object] | 查询到的音色列表。 |
| output.voice_list.voice_id | string | 音色ID。 |
| output.voice_list.gmt_create | string | 创建时间。 |
| output.voice_list.gmt_modified | string | 修改时间。 |
| output.voice_list.status | string | 音色状态,取值参见"音色状态说明"。 |
| output.voice_list.voice_prompt | string | 声音描述文本。 |
| output.voice_list.preview_text | string | 预览音频文本。 |
| usage | object | 本次请求用量信息。 |
| usage.count | integer | 固定为1。 |
查询音色详情
请求体
| 参数 | 类型 | 说明 |
|---|---|---|
| model | string | (必选) 声音设计模型。固定为voice-enrollment(Qwen-Audio-TTS/CosyVoice声音设计)。 |
| input | object | (必选) 输入参数对象。 |
| input.action | string | (必选) 操作类型。固定为query_voice。 |
| input.voice_id | string | (条件必选) 要查询的音色ID。 |
返回体
| 参数 | 类型 | 说明 |
|---|---|---|
| request_id | string | 本次调用的唯一标识符。 |
| output | object | 模型返回的数据。 |
| output.voice_id | string | 音色ID。 |
| output.gmt_create | string | 创建时间。 |
| output.gmt_modified | string | 修改时间。 |
| output.status | string | 音色状态,取值参见"音色状态说明"。 |
| output.target_model | string | 驱动音色的语音合成模型。 |
| output.voice_prompt | string | 声音描述文本。 |
| output.preview_text | string | 预览音频文本。 |
| usage | object | 本次请求用量信息。 |
| usage.count | integer | 固定为1。 |
删除音色
请求体
| 参数 | 类型 | 说明 |
|---|---|---|
| model | string | (必选) 声音设计模型。固定为voice-enrollment(Qwen-Audio-TTS/CosyVoice声音设计)。 |
| input | object | (必选) 输入参数对象。 |
| input.action | string | (必选) 操作类型。固定为delete_voice。 |
| input.voice_id | string | (条件必选) 要删除的音色ID。 |
返回体
| 参数 | 类型 | 说明 |
|---|---|---|
| request_id | string | 本次调用的唯一标识符。 |
| output | object | 模型返回的数据,返回空对象。 |
| usage | object | 本次请求用量信息。 |
| usage.count | integer | 固定为1。 |
音色状态说明
音色创建后会经过审核流程,以下是各状态的含义。
| 状态 | 说明 |
|---|---|
| DEPLOYING | 审核中/处理中。 |
| OK | 审核通过,可正常使用。 |
| UNDEPLOYED | 审核未通过,不可使用。 |