rtc_prd/API相关/豆包精品长文本语音合成-API接口文档.md

接口说明

精品长文本语音合成为异步合成服务，提供“创建合成任务”和“查询合成结果”两个接口，也可通过http回调获取合成结果。 请确认是否可满足业务需求再进行接入，本产品适用于需要批量合成较长文本，且对返回时效性无强需求的场景，单次可支持10万字符以内文本，异步返回音频。对于输入的文本请求，会进入集群排队处理，返回时长会受集群负载影响波动，通常返回时间会在数十分钟，最长返回时延3小时以内。如出现长时间未返回情况，如无报错，请耐心等待。 长文本合成分为“普通版”和“情感预测版”，两者需要开通不同的服务，接口地址不同，支持的音色列表也不相同，请仔细阅读文档。 :::warning 创建合成任务的频率限制为10 QPS，请勿一次性提交过多任务。 本产品不适合对于时效性有强需求的场景，如有需求建议接入语音合成（短文本）接口。 :::

鉴权

请求接口时，需要携带Resource-Id和Authorization两个header，缺一不可。

参考文档：鉴权方法

创建合成任务

请求参数

| | | \

服务类型	接口地址
普通版	https://openspeech.bytedance.com/api/v1/tts_async/submit
情感预测版	https://openspeech.bytedance.com/api/v1/tts_async_with_emotion/submit

请求方式：POST Content-Type： application/json 请求参数说明：

| | | | | \

参数名称	参数类型	是否必需	描述
appid	string	Y	Appid从控制台获取
reqid	string	Y	Request ID，不可重复，长度20～64，建议使用uuid
text	string	Y	合成文本，长度小于10万字符，支持SSML。SSML需要以开头和结束，且全文只出现一组标签，支持的SSML标签可参考SSML标记语言
format	string	Y	输出音频格式，支持pcm/wav/mp3/ogg_opus
voice_type	string	Y	音色voice_type，见音色列表
voice	string	N	音色voice，情感预测版voice为空时，使用预测结果；voice不为空时，使用指定的voice；其余情况使用默认voice
language	string	N	语种，与音色有关，具体值参考音色列表，默认为中文
sample_rate	int	N	采样率，默认为24000
volume	float	N	音量，范围0.1～3，默认为1
speed	float	N	语速，范围0.2～3，默认为1
pitch	float	N	语调，范围0.1～3，默认为1
enable_subtitle	int	N	是否开启字幕时间戳，0表示不开启，1表示开启句级别字幕时间戳，2表示开启字词级别时间戳，3表示开启音素级别时间戳
sentence_interval	int	N	句间停顿，单位毫秒，范围0～3000，默认为预测值
style	string	N	指定情感，“情感预测版”默认为预测值，“普通版”默认为音色默认值，音色支持的情感见音色列表
callback_url	string	N	回调返回地址建议使用域名方式；

:::warning 在 “情感预测版”接口中使用不支持多情感的音色，将会合成失败。是否支持多情感见音色列表 ::: 请求参数示例：

{
    "appid": "123456",
    "text": "火山引擎异步长文本合成。",
    "format": "mp3",
    "voice_type": "BV701_streaming",
    "sample_rate": 24000,
    "volume": 1.2,
    "speed": 0.9,
    "pitch": 1.1,
    "enable_subtitle": 1,
    "callback_url": "http://x.y.z/callback"
}

返回结果

返回结果示例： 请求成功：

{
  "task_id": "bd0c2171-4b38-4c05-b685-11f3d240ee8d",
  "task_status": 0,
  "text_length": 12
}

请求失败：

{
  "reqid": "e8f41275-72a3-45b5-af3c-61047f406cac",
  "code": 40000,
  "message": "请求参数错误：text不能为空"
}

返回参数说明：

| | | | \

参数名称	类型	描述
task_id	string	任务ID，注意保存，用于查询合成结果
task_status	int	任务状态，0-合成中，1-合成成功，2-合成失败
text_length	int	合成需要消耗的字符数，含标点符号
code	int	错误码，参考错误码说明
message	string	错误信息

查询合成结果

请求参数

| | | \

服务类型	接口地址
普通版	https://openspeech.bytedance.com/api/v1/tts_async/query
情感预测版	https://openspeech.bytedance.com/api/v1/tts_async_with_emotion/query

请求方式：GET 请求参数说明：

| | | | | \

参数名称	参数类型	是否必需	描述
appid	string	Y	Appid从控制台获取
task_id	string	Y	创建合成任务时返回的task_id

请求参数示例：

https://openspeech.bytedance.com/api/v1/tts_async/query?appid=123456&task_id=bd0c2171-4b38-4c05-b685-11f3d240ee8d

返回结果

返回结果示例： 请求成功：

{
  "task_id": "bd0c2171-4b38-4c05-b685-11f3d240ee8d",
  "task_status": 1,
  "text_length": 12,
  "audio_url": "https://lf9-lab-speech-tt-sign.bytetos.com/tos-cn-o-14155/aef41ebf89124edba16d4e97e455e007?x-expires=1687778318&x-signature=SJub692wmwsxboJTgl2VX55tIzY%3D",
  "url_expire_time": 1687777943,
  "sentences": [
    {
      "text": "火山引擎异步长文本合成。",
      "origin_text": "火山引擎异步长文本合成。",
      "paragraph_no": 1,
      "begin_time": 0,
      "end_time": 4211,
      "emotion": "neutral"
      "words": [
        {
           "text": "火",
          "begin": 25,
          "end": 235,
          "phonemes": [
            { "ph": "C0h", "begin": 25, "end": 130 },
            { "ph": "C0uo", "begin": 130, "end": 235 }
          ]
        },
        {
           "text": "山",
          "begin": 235,
          "end": 495,
          "phonemes": [
            { "ph": "C0sh", "begin": 235, "end": 345 },
            { "ph": "C0an", "begin": 345, "end": 495 }
          ]
        },
        ...
      ]
    }
  ]
}

请求失败：

{
  "reqid": "bd0c2171-4b38-4c05-b685-11f3d240ee8d",
  "code": 40001,
  "message": "没有可以合成的有效字符"
}

返回参数说明：

| | | | \

参数名称	类型	描述
task_id	string	任务ID
task_status	int	任务状态，0-合成中，1-合成成功，2-合成失败
text_length	int	合成消耗的字符数，含标点符号
audio_url	string	音频URL，有效期为1个小时，请及时下载
url_expire_time	int	音频URL过期时间（UNIX时间戳）
sentences	List	分句信息，enable_subtitle≥1才会返回
sentences.text	string	实际合成的文本，会过滤掉一些符号、表情和无法合成的字符
sentences.origin_text	string	原文分句，所有句子拼起来与输入文本完全一致
sentences.paragraph_no	int	分句所属段落，以换行符\n或 划分段落
sentences.begin_time	int	分句开始时间，单位：毫秒
sentences.end_time	int	分句结束时间，单位：毫秒
sentences.emotion	string	分句情感，“情感预测版”才会返回
sentences.words	List	字词信息，enable_subtitle≥2才会返回
sentences.words.text	string	字词文本
sentences.words.begin	int	字词开始时间，单位：毫秒
sentences.words.end	int	字词结束时间，单位：毫秒
sentences.words.phonemes	List	音素信息，enable_subtitle=3才会返回
sentences.words.phonemes.ph	string	音素
sentences.words.phonemes.begin	int	音素开始时间，单位：毫秒
sentences.words.phonemes.end	int	音素结束时间，单位：毫秒

:::warning

1. 合成结果保留7天，7天内都可以通过该接口查询合成结果，过期后自动删除。
2. 下载URL有效期为1小时，请勿直接保存audio_url，应及时下载音频或转存至你的云存储中。
3. audio_url过期后（状态码401或403），可重新请求查询接口获取新的URL。 :::

错误码说明

| | | | \

错误码	错误码描述	解决办法
40000	请求参数错误	根据返回的message检查请求参数
40001	没有可以合成的有效字符	检查请求参数中的text
40002	该音色不支持多情感	可用音色见音色列表 ，或使用“普通版”合成
40300	试用额度不足	开通正式版服务
40400	任务不存在或已过期	检查task_id是否正确
50000	服务器错误	建议先重试，重试无效请联系客服
50001	合成失败	建议先重试，重试无效请联系客服
50002	生成下载URL失败	建议先重试，重试无效请联系客服

结果回调

如果“创建合成任务”时传入了callback_url，服务器将会在合成成功/失败时，以接口回调的方式通知用户。 请求方式：POST Content-Type： application/json 回调参数示例: 合成成功：

{
   "code": 0,
  "message": "Success"
  "task_id": "bd0c2171-4b38-4c05-b685-11f3d240ee8d",
  "task_status": 1,
  "text_length": 12,
  "audio_url": "https://lf9-lab-speech-tt-sign.bytetos.com/tos-cn-o-14155/aef41ebf89124edba16d4e97e455e007?x-expires=1687778318&x-signature=SJub692wmwsxboJTgl2VX55tIzY%3D",
  "url_expire_time": 1687777943,
  "sentences": [
    ...
  ]
}

合成失败：

{
    "code": 40001,
    "message": "没有可以合成的有效字符",
    "task_id": "bd0c2171-4b38-4c05-b685-11f3d240ee8d",
    "task_status": 2,
    "text_length": 12
}

:::warning 不保证回调成功，建议在提交任务一定时间后（如3个小时）仍未收到回调，则主动请求“查询合成结果”接口。 :::