音色克隆和查询接口
更新时间：2024-12-24
接口说明
接口调用域名：https://open.xiling.baidu.com
接口包括提交音色克隆任务，查询克隆任务，查询克隆音色和系统公共音色列表。
接口鉴权和通用字段说明请查阅：接口通用说明
调用本接口需要在平台购买音色克隆组件商品并绑定到应用，操作说明参考：平台操作指引
音色克隆素材要求
| 音频要求 | 1. 上传的音频文件格式需为：mp3、m4a、wav格式； 2. 上传的音频文件的时长最少应不低于30秒，最长应不超过5分钟； 3. 上传的音频文件大小需不超过20MB。 |
|---|---|
| 录制环境 | 录音环境的选择主要考虑降低噪音和混响，建议使用10平方米以内的小房间进行录音，有吸音装置的房间是理想环境。可使用价格低廉的吸音棉对房间进行改造，目的是为了改变声波的平面反射为漫反射，降低混响。 1. 尽量在同一声学环境下录制，避免过于喧哗的背景音和噪音，音频非拼接而成。 2. 避免远场环境下录制，建议离麦克风50cm之内,并需要保持位置、距离稳定，防止音量大小不一致。不要让讲话的气流正对麦克风，防止喷麦造成的噪音。 3. 尽量在自然对话状态下录制,对比刻意压低声线/呢喃获得的音色会更贴合本人。 |
| 音频质量 | 1. 必须仅含有一个人在说话，避免多个人同时说话。 2. 说话人发音及音质越清晰、复刻质量越高。如说话人喉音/声音底噪严重，则复刻音频喉音和底噪将会较为严重。 3. 录音时需要保持音量大小、语速稳定、注意断句、避免口腔噪音(如口水声)、杂音、混响等情况。结合最终使用场景与人设加入适当演绎，避免朗读风格过于严重，并保持整体风格一致。 4. 录音时尽量保持姿态稳定，减少不必要的肢体动作，椅子的响声、衣物的摩擦音、鼠标键盘的敲击声都是常见的人为噪声，需要格外注意细节。 5. 如口误无需终止录音，可停顿1~2秒后，继续录制即可。 |
| 录制内容 | 建议在录音前熟悉文案，并确定好人设及演绎风格。尽量贴近复刻内容和主题，避免说话人韵律过于平淡，否则将得到较平的复刻效果。如需要复刻情绪韵律起伏较强的音频，请尽量输入表现力强的音频。尽量不要尝试复刻小孩或者老人的音频。 |
接口列表
发起克隆任务
接口说明
上传音频文件，发起一个克隆任务。发起后接收任务结束的回调通知，或使用音色ID轮询任务状态（不建议）。
接口协议
POST /api/digitalhuman/open/v1/tts/clone/v2
Content-Type: application/json;charset=utf-8
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | String | 是 | 克隆音色的名字，长度不超过 50，当前账户下需唯一 |
| describe | String | 否 | 克隆音色的描述，长度不超过 100 |
| gender | String | 否 | 性别 (male / female / unknown) |
| uploadAudioId | String | 是 | 用于训练的音频文件ID，使用文件上传接口接口上传后获取文件ID，providerType 参数固定填写 OPEN_TTS_CLONE 1.时长在 30 秒到 5 分钟 2.大小低于 20MB 3.格式为 mp3/wav/m4a |
| exampleText | String | 是 | 试听音频的文本，长度不超过 100 |
| callbackUrl | String | 否 | 接口调用方接受任务回调通知的url，规则和接口说明参考接口通用说明，回调消息定义见下面的回调接口参数说明。 |
返回参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| perId | String | 是 | 克隆音色的id |
错误码
| 错误码 | 描述 |
|---|---|
| 0 | 正常返回 |
| 4911 | 找不到app信息，请确认appId是否输入正确 |
| 4913 | 无法访问API，可能是app没有绑定对应的组件，或url输入错误，或访问的人像不可用 |
| 10001 | 签名校验失败 |
| 10002 | 签名信息为空 |
| 10003 | 签名格式错误 |
| 10004 | 未识别错误的通用错误码 |
| 10005 | 请求体JSON解析失败，请确认是否是合法的JSON格式 |
| 10006 | 参数校验不通过 |
| 10011 | 没有购买对应的商品 |
| 14001 | 内部服务异常，请稍后再试 |
| 14002 | 内部服务异常，网络拥堵 |
| 10006 | 参数校验不通过 |
| 23001 | 语音服务内部调用异常，需联系平台解决 |
| 23003 | 克隆音色名字已存在 |
请求示例
{
"requestId": "589e3dc4-0d78-48a5-8471-cf262daf8e67",
"name": "mockname6",
"describe": "thisisamockdesc",
"gender": "male",
"uploadAudioId": "617913c8-6b3c-4d30-8853-e2d0f8309768",
"exampleText": "您好，欢迎来到曦灵数字人平台，我可以24小时在线直播",
"callbackUrl": "http://callback/path"
}返回示例
{
"code": 0,
"message": {
"global": "success"
},
"result": {
"perId": "10000079"
},
"requestId": "589e3dc4-0d78-48a5-8471-cf262daf8e67",
"success": true
}回调接口参数
规则和接口说明参考接口通用说明，回调消息定义如下：
- type: TTS_CLONE
- data:
| 参数名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| perId | String | 是 | 克隆音色的id |
| name | String | 是 | 名称 |
| gender | String | 否 | 性别信息 (male / female / unknown) |
| describe | String | 否 | 描述信息 |
| status | String | 是 | 状态： SUCCESS(克隆成功), FAIL(克隆失败) |
| exampleText | String | 否 | 示例文本 |
| exampleAudioUrl | String | 否 | 示例音频URL |
| reason | String | 否 | 失败原因，如果状态为失败则会出现此字段 |
查询音色克隆任务列表
接口说明
查询音色克隆任务列表。
接口协议
GET /api/digitalhuman/open/v1/tts/clone?isSuccess=false请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| isSuccess | boolean | 是 | 是否只查询克隆成功的任务(true: 只查询成功的任务， false: 查询全部克隆任务) |
| perId | String | 否 | 查询指定 perId 的克隆任务 |
返回参数
| 参数名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| perId | String | 是 | 克隆音色的id |
| name | String | 是 | 名称 |
| describe | String | 是 | 描述 |
| exampleText | String | 是 | 示例文本 |
| exampleAudioUrl | String | 是 | 示例音频URL |
| status | String | 是 | 当前状态：PREPARING(准备中), CLONING(克隆中), SUCCESS(克隆成功), FAIL(克隆失败) |
| reason | String | 是 | 失败原因，如果状态为 FAIL 则会出现此字段 |
| version | String | 是 | 音色版本，如 V2 |
| gender | String | 是 | 性别信息 (male / female / unknown) |
请求示例
GET /api/digitalhuman/open/v1/tts/clone?isSuccess=false返回示例
{
"code": 0,
"message": {
"global": "success"
},
"result": [
{
"perId": "10000079",
"name": "mockname",
"describe": "thisisamockdesc",
"exampleText": "您好，欢迎来到曦灵数字人平台，我可以24小时在线直播",
"exampleAudioUrl": "",
"status": "FAIL",
"reason": "accountId(73894c599b274247a087fed65727e04a), userId(73894c599b274247a087fed65727e04a) 配额余额不足",
"version": "V2",
"gender": "male"
},
{
"perId": "10000070",
"name": "test",
"describe": "this is a mock desc",
"exampleText": "您好，欢迎来到曦灵数字人平台，我可以24小时在线直播",
"exampleAudioUrl": "",
"status": "FAIL",
"reason": "ConvertToMono failed,error:exit status 251",
"version": "V2",
"gender": "male"
}
],
"requestId": "d2404d3b-81fb-4cd3-81ee-4feb926fd5d1",
"success": true
}查询音色列表
接口说明
查询音色，包括克隆音色和系统库提供的公共音色。
接口协议
GET /api/digitalhuman/open/v1/tts/persons?isSystem=true请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| isSystem | boolean | 否 | 是否只查询系统音色： - true: 只查询系统音色 - false: 只查询克隆音色 - 不传：查询所有可用音色 |
返回参数
| 参数名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| perId | String | 是 | 克隆音色的id |
| name | String | 是 | 音色名称 |
| describe | String | 否 | 描述 |
| version | String | 是 | 音色版本，如 V2 |
| exampleAudioUrl | String | 否 | 示例音频 URL |
| gender | String | 否 | 性别信息 (male / female / unknown) |
| systemProvided | boolean | 是 | 是否是系统音色 |
请求示例
GET /api/digitalhuman/open/v1/tts/persons?isSystem=true返回示例
{
"code": 0,
"message": {
"global": "success"
},
"result": [
{
"perId": "10001251",
"name": "test123",
"describe": "thisisamockdesc",
"version": "V2",
"exampleAudioUrl": null,
"gender": "female",
"systemProvided": true
},
{
"perId": "100051",
"name": "自信活泼小姐姐",
"describe": "青年，开朗活泼",
"version": "V2",
"exampleAudioUrl": null,
"gender": "female",
"systemProvided": true
}
],
"requestId": "d2404d3b-81fb-4cd3-81ee-4feb926fd5d1",
"success": true
}