You need to enable JavaScript to run this app.
导航

API接口文档

最近更新时间2024.02.02 12:57:28

首次发布时间2023.06.29 16:18:04

接口说明

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

注意

创建合成任务的频率限制为10 QPS,请勿一次性提交过多任务。
本产品不适合对于时效性有强需求的场景,如有需求建议接入语音合成(短文本)接口。

鉴权

请求接口时,需要携带Resource-IdAuthorization两个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
请求参数说明:

参数名称参数类型是否必需描述
appidstringYAppid从控制台获取
reqidstringYRequest ID,不可重复,长度20~64,建议使用uuid
textstringY合成文本,长度小于10万字符,支持SSML。SSML需要以<speak>开头和</speak>结束,且全文只出现一组<speak>标签,支持的SSML标签可参考SSML标记语言
formatstringY输出音频格式,支持pcm/wav/mp3/ogg_opus
voice_typestringY音色voice_type,见音色列表
voicestringN音色voice,情感预测版voice为空时,使用预测结果;voice不为空时,使用指定的voice;其余情况使用默认voice
languagestringN语种,与音色有关,具体值参考音色列表,默认为中文
sample_rateintN采样率,默认为24000
volumefloatN音量,范围0.1~3,默认为1
speedfloatN语速,范围0.2~3,默认为1
pitchfloatN语调,范围0.1~3,默认为1
enable_subtitleintN是否开启字幕时间戳,0表示不开启,1表示开启句级别字幕时间戳,2表示开启字词级别时间戳,3表示开启音素级别时间戳
sentence_intervalintN句间停顿,单位毫秒,范围0~3000,默认为预测值
stylestringN指定情感,“情感预测版”默认为预测值,“普通版”默认为音色默认值,音色支持的情感见音色列表
callback_urlstringN回调地址,支持http和https,使用方法见结果回调

注意

在 “情感预测版”接口中使用不支持多情感的音色,将会合成失败。是否支持多情感见音色列表

请求参数示例:

{
    "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_idstring任务ID,注意保存,用于查询合成结果
task_statusint任务状态,0-合成中,1-合成成功,2-合成失败
text_lengthint合成需要消耗的字符数,含标点符号
codeint错误码,参考错误码说明
messagestring错误信息
查询合成结果

请求参数

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

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

参数名称参数类型是否必需描述
appidstringYAppid从控制台获取
task_idstringY创建合成任务时返回的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_idstring任务ID
task_statusint任务状态,0-合成中,1-合成成功,2-合成失败
text_lengthint合成消耗的字符数,含标点符号
audio_urlstring音频URL,有效期为1个小时,请及时下载
url_expire_timeint音频URL过期时间(UNIX时间戳)
sentencesList分句信息,enable_subtitle≥1才会返回
sentences.textstring实际合成的文本,会过滤掉一些符号、表情和无法合成的字符
sentences.origin_textstring原文分句,所有句子拼起来与输入文本完全一致
sentences.paragraph_noint分句所属段落,以换行符\n或</p>划分段落
sentences.begin_timeint分句开始时间,单位:毫秒
sentences.end_timeint分句结束时间,单位:毫秒
sentences.emotionstring分句情感,“情感预测版”才会返回
sentences.wordsList字词信息,enable_subtitle≥2才会返回
sentences.words.textstring字词文本
sentences.words.beginint字词开始时间,单位:毫秒
sentences.words.endint字词结束时间,单位:毫秒
sentences.words.phonemesList音素信息,enable_subtitle=3才会返回
sentences.words.phonemes.phstring音素
sentences.words.phonemes.beginint音素开始时间,单位:毫秒
sentences.words.phonemes.endint音素结束时间,单位:毫秒

注意

  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
}

注意

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