参数基本说明--语音技术-火山引擎

文档中心

导航

参数基本说明

最近更新时间：2025.03.24 12:25:13首次发布时间：2021.12.20 14:44:12

请求参数

字段	含义	层级	格式	必需	备注
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元）