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

<span id="创建合成任务"></span>
# 创建合成任务
<span id="请求参数"></span>
## 请求参数

| | | \
|服务类型 |接口地址 |
|---|---|
| | | \
|普通版 |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需要以<speak>开头和</speak>结束，且全文只出现一组<speak>标签，支持的SSML标签可参考[SSML标记语言](/docs/6561/104897) |
| | | | | \
|format |string |Y |输出音频格式，支持pcm/wav/mp3/ogg_opus |
| | | | | \
|voice_type |string |Y |音色voice_type，见[音色列表](/docs/6561/1108211) |
| | | | | \
|voice |string |N |音色voice，情感预测版voice为空时，使用预测结果；voice不为空时，使用指定的voice；其余情况使用默认voice |
| | | | | \
|language |string |N |语种，与音色有关，具体值参考[音色列表](/docs/6561/1108211)，默认为中文 |
| | | | | \
|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 |指定情感，“情感预测版”默认为预测值，“普通版”默认为音色默认值，音色支持的情感见[音色列表](/docs/6561/1108211) |
| | | | | \
|callback_url |string |N |回调返回地址建议使用域名方式； |

:::warning
在 “情感预测版”接口中使用不支持多情感的音色，将会合成失败。是否支持多情感见[音色列表](/docs/6561/1108211)
:::
**请求参数示例：**
```json
{
    "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"
}
```

<span id="返回结果"></span>
## 返回结果
**返回结果示例：**
请求成功：
```json
{
  "task_id": "bd0c2171-4b38-4c05-b685-11f3d240ee8d",
  "task_status": 0,
  "text_length": 12
}
```

请求失败：
```json
{
  "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 |错误码，参考[错误码说明](/docs/6561/1096680#错误码说明) |
| | | | \
|message |string |错误信息 |

<span id="查询合成结果"></span>
# 查询合成结果
<span id="请求参数"></span>
## 请求参数

| | | \
|服务类型 |接口地址 |
|---|---|
| | | \
|普通版 |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 |

**请求参数示例：**
```GET
https://openspeech.bytedance.com/api/v1/tts_async/query?appid=123456&task_id=bd0c2171-4b38-4c05-b685-11f3d240ee8d
```

<span id="返回结果"></span>
## 返回结果
**返回结果示例：**
请求成功：
```json
{
  "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 }
          ]
        },
        ...
      ]
    }
  ]
}
```

请求失败：
```json
{
  "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或</p>划分段落 |
| | | | \
|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。
:::
<span id="错误码说明"></span>
# 错误码说明

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

<span id="结果回调"></span>
# 结果回调
如果“创建合成任务”时传入了**callback_url**，服务器将会在合成成功/失败时，以接口回调的方式通知用户。
**请求方式：`POST`**
**Content-Type：** `application/json`
**回调参数示例:**
合成成功：
```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": [
    ...
  ]
}
```

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

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