字段 | 含义 | 层级 | 格式 | 必需 | 备注 |
---|---|---|---|---|---|
app | 应用相关配置 | 1 | dict | ✓ | |
appid | 应用标识 | 2 | string | ✓ | 需要申请,具体见控制台使用FAQ1 |
token | 应用令牌 | 2 | string | ✓ | 可传入任意非空值 |
cluster | 业务集群 | 2 | string | ✓ | 标准音色、复刻等均不相同,具体见控制台使用FAQ1 |
user | 用户相关配置 | 1 | dict | ✓ | |
uid | 用户标识 | 2 | string | ✓ | 可传入任意非空值,传入值可以通过服务端日志追溯 |
audio | 音频相关配置 | 1 | dict | ✓ | |
voice_type | 音色类型 | 2 | string | ✓ | 发音人参数列表,复刻音色使用声音ID(speaker id) |
rate | 音频采样率 | 2 | int | 默认为 24000,可选8000,16000 | |
encoding | 音频编码格式 | 2 | string | wav / pcm / ogg_opus / mp3,默认为 pcm 注意:wav 不支持流式 | |
compression_rate | opus格式时编码压缩比 | 2 | int | [1, 20],默认为 1 | |
speed_ratio | 语速 | 2 | float | [0.2,3],默认为1,通常保留一位小数即可 | |
volume_ratio | 音量 | 2 | float | 0.1, 3],默认为1,通常保留一位小数即可 | |
pitch_ratio | 音高 | 2 | float | [0.1, 3],默认为1,通常保留一位小数即可 | |
emotion | 情感/风格 | 2 | string | 发音人参数列表 | |
language | 语言类型 | 2 | string | 发音人参数列表 | |
request | 请求相关配置 | 1 | dict | ✓ | |
reqid | 请求标识 | 2 | string | ✓ | 需要保证每次调用传入值唯一,建议使用 UUID |
text | 文本 | 2 | string | ✓ | 合成语音的文本,长度限制 1024 字节(UTF-8编码)。复刻音色没有此限制,但是HTTP接口有60s超时限制 |
text_type | 文本类型 | 2 | string | plain / ssml, 默认为plain | |
silence_duration | 句尾静音时长 | 2 | int | 单位为ms,默认为125 | |
operation | 操作 | 2 | string | ✓ | query(非流式,http只能query) / submit(流式) |
with_frontend | 时间戳相关 | 2 | int string | 当with_frontend为1且frontend_type为unitTson的时候,返回音素级时间戳 | |
frontend_type | 时间戳相关 | 2 | int string | 当with_frontend为1且frontend_type为unitTson的时候,返回音素级时间戳 | |
with_timestamp | 时间戳相关 | 2 | int string | 传入1时表示启用。新版时间戳参数,可用来替换with_frontend和frontend_type,可返回原文本的时间戳,而非TN后文本,即保留原文中的阿拉伯数字或者特殊符号等。注意:原文本中的多个标点连用或者空格依然会被处理,但不影响时间戳连贯性 | |
split_sentence | 复刻音色语速优化 | 2 | int string | 仅当使用复刻音色时设为1,可优化语速过快问题。有可能会导致时间戳多次返回。详情可见:声音复刻录音指导-badcase优化建议2 | |
pure_english_opt | 英文前端优化 | 2 | int string | 当pure_english_opt为1的时候,中文音色读纯英文时可以正确处理文本中的阿拉伯数字 |
请求示例
{ "app": { "appid": "appid123", "token": "access_token", "cluster": "volcano_tts", }, "user": { "uid": "uid123" }, "audio": { "voice_type": "BV700_streaming", "encoding": "mp3", "compression_rate": 1, "rate": 24000, "speed_ratio": 1.0, "volume_ratio": 1.0, "pitch_ratio": 1.0, "emotion": "happy", "language": "cn" }, "request": { "reqid": "uuid", "text": "字节跳动语音合成", "text_type": "plain", "operation": "query", "silence_duration": "125", "with_frontend": "1", "frontend_type": "unitTson", "pure_english_opt": "1" } }
字段 | 含义 | 层级 | 格式 | 备注 |
---|---|---|---|---|
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 |
frontend | 时间戳信息 | 2 | string | 包含字级别和音素级别的时间戳信息 |
响应示例
{ "reqid": "reqid", "code": 3000, "operation": "query", "message": "Success", "sequence": -1, "data": "base64 encoded binary data", "addition": { "description": "...", "duration": "1960", "frontend": "{ "words": [{ "word": "字", "start_time": 0.025, "end_time": 0.185 }, ... { "word": "。", "start_time": 1.85, "end_time": 1.955 }], "phonemes": [{ "phone": "C0z", "start_time": 0.025, "end_time": 0.105 }, ... { "phone": "。", "start_time": 1.85, "end_time": 1.955 }] }" } }
错误码 | 错误描述 | 举例 | 建议行为 |
---|---|---|---|
3000 | 请求正确 | 正常合成 | 正常处理 |
3001 | 无效的请求 | 一些参数的值非法,比如operation/workflow配置错误 | 检查参数 |
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元)