注意
声音复刻从2024.07.10开始提供2.0升级效果。所有还剩余训练次数的音色均可以调用2.0训练接口进行训练。调用时注意传递model_type=1,另外原始音频如果不是中文也必须指定语种。
注意
model_type=1时,合成采样率只支持24000,另外在合成时需要替换cluster。
如使用字符版,控制台显示的旧cluster为volcano_mega,需替换为volcano_icl;
如使用并发版,控制台显示的旧cluster为volcano_mega_concurr,需替换为volcano_icl_concurr
域名: https://openspeech.bytedance.com
具体请求方式可参考下方示例代码
接口路径: POST
/api/v1/mega_tts/audio/upload
接口描述: 提交音频训练音色
认证方式使用Bearer Token,在请求的header中加上"Authorization": "Bearer; {token}"
,并在请求的json中填入对应的appid。
注意
Bearer和token使用分号 ; 分隔,替换时请勿保留{}
AppID/Token/Cluster 等信息可参考 控制台使用FAQ-Q1
Header:
参数名称 | 参数类型 | 必须参数 | 备注 |
---|---|---|---|
Authorization | string | 必填 | Bearer;${Access Token} |
Resource-Id | string | 必填 | 填入volc.megatts.voiceclone |
Body:
参数名称 | 层级 | 参数类型 | 必须参数 | 备注 |
---|---|---|---|---|
appid | 1 | string | 必填 | |
speaker_id | 1 | string | 必填 | 唯一音色代号 |
audios | 1 | list | 必填 | 音频格式支持:wav、mp3、ogg、m4a、aac、pcm,其中pcm仅支持24k 单通道目前限制单文件上传最大10MB,每次最多上传1个音频文件 |
audio_bytes | 2 | string | 必填 | 二进制音频字节,需对二进制音频进行base64编码 |
audio_format | 2 | string | 音频格式,pcm、m4a必传,其余可选 | |
text | 2 | string | 可以让用户按照该文本念诵,服务会对比音频与该文本的差异。若差异过大会返回1109 WERError | |
source | 1 | int | 必填 | 固定值:2 |
language | 1 | int | cn = 0 中文(默认) | |
model_type | 1 | int | 默认为0 |
json示例
{ "speaker_id": "S_*******", "appid": "your appid", "audios": [{ "audio_bytes": "base64编码后的音频", "audio_format": "wav" }], "source": 2, "language": 0, "model_type": 1 }
Body:
参数名称 | 层级 | 参数类型 | 必须参数 | 备注 |
---|---|---|---|---|
BaseResp | 1 | object | 必填 | |
StatusCode | 2 | int | 必填 | 成功:0 |
StatusMessage | 2 | string | 错误信息 | |
speaker_id | 1 | string | 必填 | 唯一音色代号 |
json示例
{ "BaseResp":{ "StatusCode":0, "StatusMessage":"" }, "speaker_id":"S_*******" }
Success | 0 | 成功 |
---|---|---|
BadRequestError | 1001 | 请求参数有误 |
AudioUploadError | 1101 | 音频上传失败 |
ASRError | 1102 | ASR(语音识别成文字)转写失败 |
SIDError | 1103 | SID声纹检测失败 |
SIDFailError | 1104 | 声纹检测未通过,声纹跟名人相似度过高 |
GetAudioDataError | 1105 | 获取音频数据失败 |
SpeakerIDDuplicationError | 1106 | SpeakerID重复 |
SpeakerIDNotFoundError | 1107 | SpeakerID未找到 |
AudioConvertError | 1108 | 音频转码失败 |
WERError | 1109 | wer检测错误,上传音频与请求携带文本对比字错率过高 |
AEDError | 1111 | aed检测错误,通常由于音频不包含说话声 |
SNRError | 1112 | SNR检测错误,通常由于信噪比过高 |
DenoiseError | 1113 | 降噪处理失败 |
AudioQualityError | 1114 | 音频质量低,降噪失败 |
ASRNoSpeakerError | 1122 | 未检测到人声 |
已达上传次数限制 | 1123 | 上传接口已经达到次数限制,目前同一个音色支持10次上传 |
接口路径: POST
/api/v1/mega_tts/status
接口描述: 查询音色训练状态
Header:
参数名称 | 参数类型 | 必须参数 | 备注 |
---|---|---|---|
Authorization | string | 必填 | Bearer;${Access Token} |
Resource-Id | string | 必填 | 填入volc.megatts.voiceclone |
Body:
参数名称 | 层级 | 类型 | 必填 | 备注 |
---|---|---|---|---|
appid | 1 | string | 必填 | |
speaker_id | 1 | string | 必填 | 唯一音色代号 |
json示例
{ "appid": "your appid", "speaker_id": "S_*******" }
Body:
参数名称 | 层级 | 参数类型 | 必须参数 | 备注 |
---|---|---|---|---|
BaseResp | 1 | object | 必填 | |
StatusCode | 2 | int | 必填 | 成功:0 |
StatusMessage | 2 | string | 错误信息 | |
speaker_id | 1 | string | 必填 | 唯一音色代号 |
status | 1 | enum { NotFound = 0 Training = 1 Success = 2 Failed = 3 Active = 4 } | 必填 | 训练状态,状态为2或4时都可以调用tts |
create_time | 1 | int | 必填 | 创建时间 |
version | 1 | string | 选填 | 训练版本 |
demo_audio | 1 | string | 选填 | Success状态时返回,一小时有效,若需要,请下载后使用 |
json示例
{ "BaseResp":{ "StatusCode":0, "StatusMessage":"" }, "creaet_time":1701055304000, "version": "V1", "demo_audio": "http://**********.wav" "speaker_id":"S_*******", "status":2 }
接口调用方式与TTS一致,可以参考如下链接,将参数做对应修改后即可使用。
注意
采样率只支持24000,model_type=1时,cluster必须使用volcano_icl或volcano_icl_concurr
使用账号申请部分申请到的appid&access_token进行调用
文本一次性送入,后端边合成边返回音频数据
使用账号申请部分申请到的appid&access_token进行调用
文本全部合成完毕之后,一次性返回全部的音频数据
字段 | 含义 | 层级 | 格式 | 必需 | 备注 |
---|---|---|---|---|---|
app | 应用相关配置 | 1 | dict | ✓ | |
appid | 应用标识 | 2 | string | ✓ | 需要申请 |
token | 应用令牌 | 2 | string | ✓ | 可传任意非空字符串 |
cluster | 业务集群 | 2 | string | ✓ | volcano_icl或volcano_icl_concurr |
user | 用户相关配置 | 1 | dict | ✓ | |
uid | 用户标识 | 2 | string | ✓ | 可传任意非空字符串,传入值可以通过服务端日志追溯 |
audio | 音频相关配置 | 1 | dict | ✓ | 语音合成参考音色列表;声音复刻语音合成请通过下单获取 |
voice_type | 音色类型 | 2 | string | ✓ | |
encoding | 音频编码格式 | 2 | string | wav / pcm / ogg_opus / mp3,默认为 pcm | |
request | 请求相关配置 | 1 | dict | ✓ | |
reqid | 请求标识 | 2 | string | ✓ | 需要保证每次调用传入值唯一,建议使用 UUID |
text | 文本 | 2 | string | ✓ | 合成语音的文本,长度限制 1024 字节(UTF-8编码) |
operation | 操作 | 2 | string | ✓ | query(非流式,http只能query) / submit(流式) |
备注:
请求示例
{ "app": { "appid": "appid123", "token": "access_token", "cluster": "volcano_icl" }, "user": { "uid": "uid123" }, "audio": { "voice_type": "S_xxxx", "encoding": "mp3", "speed_ratio": 1 }, "request": { "reqid": "uuid", "text": "字节跳动语音合成", "operation": "query" } }
字段 | 含义 | 层级 | 格式 | 备注 |
---|---|---|---|---|
reqid | 请求 ID | 1 | string | 请求 ID,与传入的参数中 reqid 一致 |
code | 请求状态码 | 1 | int | 错误码,参考下方说明 |
message | 请求状态信息 | 1 | string | 错误信息 |
sequence | 音频段序号 | 1 | int | 负数表示合成完毕 |
data | 合成音频 | 1 | string | 返回的音频数据,base64 编码 |
addition | 额外信息 | 1 | string | 额外信息父节点 |
duration | 音频时长 | 2 | string | 返回音频的长度,单位ms |
响应示例
{ "reqid": "reqid", "code": 3000, "operation": "query", "message": "Success", "sequence": -1, "data": "base64 encoded binary data", "addition": { "duration": "1960" } }
错误码 | 错误描述 | 举例 | 建议行为 |
---|---|---|---|
3000 | 请求正确 | 正常合成 | 正常处理 |
3001 | 无效的请求 | 一些参数的值非法,比如operation配置错误 | 检查参数 |
3003 | 并发超限 | 超过在线设置的并发阈值 | 重试;使用sdk的情况下切换离线 |
3005 | 后端服务忙 | 后端服务器负载高 | 重试;使用sdk的情况下切换离线 |
3006 | 服务中断 | 请求已完成/失败之后,相同reqid再次请求 | 检查参数 |
3010 | 文本长度超限 | 单次请求超过设置的文本长度阈值 | 检查参数 |
3011 | 无效文本 | 参数有误或者文本为空、文本与语种不匹配、文本只含标点 | 检查参数 |
3030 | 处理超时 | 单次请求超过服务最长时间限制 | 重试或检查文本 |
3031 | 处理错误 | 后端出现异常 | 重试;使用sdk的情况下切换离线 |
3032 | 等待获取音频超时 | 后端网络异常 | 重试;使用sdk的情况下切换离线 |
3040 | 后端链路连接错误 | 后端网络异常 | 重试 |
3050 | 音色不存在 | 检查使用的voice_type代号 | 检查参数 |
错误返回:
"message": "quota exceeded for types: xxxxxxxxx_lifetime"
错误原因:试用版用量用完了,需要开通正式版才能继续使用
错误返回:
"message": "quota exceeded for types: concurrency"
错误原因:并发超过了限定值,需要减少并发调用情况或者增购并发
错误返回:
"message": "Fail to feed text, reason Init Engine Instance failed"
错误原因:voice_type / cluster 传递错误
错误返回:
"message": "illegal input text!"
错误原因:传入的text无效,没有可合成的有效文本。比如全部是标点符号或者emoji表情,或者使用中文音色时,传递日语,以此类推。多语种音色,也需要使用language指定对应的语种
"message": "authenticate request: load grant: requested grant not found"
错误原因:鉴权失败,需要检查appid&token的值是否设置正确,同时,鉴权的正确格式为
headers["Authorization"] = "Bearer;${token}"
"message': 'extract request resource id: get resource id: access denied"
错误原因:语音合成已开通正式版且未拥有当前音色授权,需要在控制台购买该音色才能调用。标注免费的音色除BV001_streaming及BV002_streaming外,需要在控制台进行下单(支付0元)
线上请求地址域名 open.volcengineapi.com
Region = "cn-north-1" Service = "speech_saas_prod" Version = "2023-11-07" 解释
说明:Access Key(密钥)管理--API访问密钥(Access Key)-火山引擎 (volcengine.com)
结合文档内api说明调用 ListMegaTTSTrainStatus
的例子(*其他语言和使用sdk调用的方式请参考火山鉴权源码说明 一)
{ "ResponseMetadata": { "RequestId": "20220214145719010211209131054BC103", // header中的X-Top-Request-Id参数 "Action": "ListMegaTTSTrainStatus", "Version": "2023-11-07", "Service": "{Service}",// header中的X-Top-Service参数 "Region": "{Region}", // header中的X-Top-Region参数 "Error": { "Code": "InternalError.NotCaptured", "Message": "xxx" } } }
Code | Description |
---|---|
OperationDenied.InvalidSpeakerID | 账号或AppID无权限操作或无法操作SpeakerID列表中的一个或多个实例 |
OperationDenied.InvalidParameter | 请求体字段不合法(缺失必填字段、类型错误等) |
InternalError.NotCaptured | 未知的服务内部错误 |
a. Description
查询已购买的音色状态;如果SpeakerIDs为空则返回账号的AppID下所有的列表(有最大值限制1000);如果SpeakerIDs不为空则返回对应的结果,且结果总是包含输入的SpeakerID(即使查询不到它)
b. Method: POST
c. Request
Parameter | Type | Must | Argument type | Description |
---|---|---|---|---|
Content-Type | string | Y | header | 固定字符串: application/json; charset=utf-8 |
Action | string | Y | query | ListMegaTTSTrainStatus |
Version | string | Y | query | 2023/11/7 |
AppID | string | Y | body | AppID |
SpeakerIDs | []string | N | body | SpeakerID的列表,传空为返回指定APPID下的全部SpeakerID |
d. Response
{ "ResponseMetadata": { "RequestId": "20220214145719010211209131054BC103", // header中的X-Top-Request-Id参数 "Action": "", "Version": "", "Service": "{Service}",// header中的X-Top-Service参数 "Region": "{Region}" // header中的X-Top-Region参数 }, "Result":{ "Statuses": [ { "CreateTime": 1700727790000, // unix epoch格式的创建时间,单位ms "DemoAudio": "https://example.com", // http demo链接 "InstanceNO": "Model_storage_meUQ8YtIPm", // 火山引擎实例number "IsActivable": true, // 是否可激活 "SpeakerID": "S_VYBmqB0A", // speakerID "State": "Success", // speakerID的状态 "Version": "V1", // speakerID已训练过的次数 "ExpireTime": 1732895999000, //过期时间 "Alias": "", //别名,和控制台同步 "AvailableTrainingTimes": 9 //剩余训练次数,激活音色为0 }, { "SpeakerID": "S_VYBmqB0B", // speakerID "State": "Unknown", // speakerID的状态 } ] } }
e. State of speakerID is an enum with possible values of:
State | Description |
---|---|
Unknown | SpeakerID尚未进行训练 |
Training | 声音复刻训练中(长时间处于复刻中状态请联系火山引擎技术人员) |
Success | 声音复刻训练成功,可以进行TTS合成 |
Active | 已激活(无法再次训练) |
Expired | 火山控制台实例已过期或账号欠费 |
Reclaimed | 火山控制台实例已回收 |
BatchListMegaTTSTrainStatus
a. Description
查询已购买的音色状态;相比ListMegaTTSTrainStatus
增加了分页相关参数和返回;支持使用token和声明页数两种分页方式;其中,
b. Method: POST
c. Request
Parameter | Type | Must | Argument type | Description |
---|---|---|---|---|
Content-Type | Y | header | 固定字符串: application/json; charset=utf-8 | |
Action | string | Y | query | BatchListMegaTTSTrainStatus |
Version | string | Y | query | 2023/11/7 |
AppID | string | Y | body | AppID |
SpeakerIDs | []string | N | body | SpeakerID的列表,传空为返回指定APPID下的全部SpeakerID |
PageNumber | int | N | body | 页数, 需大于0, 默认为1 |
PageSize | int | N | body | 每页条数, 必须在范围[1, 100]内, 默认为10 |
NextToken | string | N | body | 上次请求返回的字符串; 如果不为空的话, 将覆盖PageNumber及PageSize的值 |
MaxResults | int | N | body | 与NextToken相配合控制返回结果的最大数量; 如果不为空则必须在范围[1, 100]内, 默认为10 |
d. Response
{ "ResponseMetadata": { "RequestId": "20220214145719010211209131054BC103", // header中的X-Top-Request-Id参数 "Action": "BatchListMegaTTSTrainStatus", "Version": "2023-11-07", "Service": "{Service}",// header中的X-Top-Service参数 "Region": "{Region}" // header中的X-Top-Region参数}, "Result": { "AppID": "xxx", "TotalCount": 2, // speakerIDs总数量 "NextToken": "", // NextToken字符串,可发送请求后面的结果; 如果没有更多结果将为空 "PageNumber": 1, // 使用分页参数时的当前页数 "PageSize": 2, // 使用分页参数时当前页包含的条数 "Statuses": [ { "CreateTime": 1700727790000, // unix epoch格式的创建时间,单位ms "DemoAudio": "https://example.com", // http demo链接 "InstanceNO": "Model_storage_meUQ8YtIPm", // 火山引擎实例Number "IsActivable": true, // 是否可激活 "SpeakerID": "S_VYBmqB0A", // speakerID "State": "Success", // speakerID的状态 "Version": "V1" // speakerID已训练过的次数 }, { "SpeakerID": "S_VYBmqB0B", // speakerID "State": "Unknown", // speakerID的状态 "Version": "V1" // speakerID已训练过的次数 } ] } }