1. 请求方式

域名： https://openspeech.bytedance.com
具体请求方式可参考下方示例代码

uploadAndStatus.py

未知大小

2. 训练（upload接口）

接口路径: POST/api/v1/mega_tts/audio/upload
接口描述: 提交音频训练音色
认证方式使用Bearer Token，在请求的header中加上"Authorization": "Bearer; {token}"，并在请求的json中填入对应的appid。

请求参数

Header:

Body:

json示例

{
        "speaker_id": "S_*******",
        "appid": "your appid",
        "audios": [{
                "audio_bytes": "base64编码后的音频",
                "audio_format": "wav"
        }],
        "source": 2,
        "language": 0,
        "model_type": 1
}

返回数据

Body:

json示例

{
    "BaseResp":{
        "StatusCode":0,
        "StatusMessage":""
    },
    "speaker_id":"S_*******"
}

3. 返回码：

4. 状态查询（status接口）

接口路径: POST/api/v1/mega_tts/status
接口描述: 查询音色训练状态

请求参数

Header:

Body:

json示例

{
    "appid": "your appid",
    "speaker_id": "S_*******"
}

返回数据

Body:

json示例

{
    "BaseResp":{
        "StatusCode":0,
        "StatusMessage":""
    },
    "creaet_time":1701055304000,
    "version": "V1",
    "demo_audio": "http://**********.wav"
    "speaker_id":"S_*******",
    "status":2
}

音色训练成功后，需要通过调用TTS接口来使用音色合成指定文本的音频。

Websocket

使用账号申请部分申请到的appid&access_token进行调用
文本一次性送入，后端边合成边返回音频数据

1. 接口说明

接口地址为 wss://openspeech.bytedance.com/api/v1/tts/ws_binary

2. 身份认证

认证方式使用Bearer Token，在请求的header中加上"Authorization": "Bearer; {token}"，并在请求的json中填入对应的appid。

AppID/Token/Cluster 等信息可参考 控制台使用FAQ-Q1

3. 请求方式

3.1 二进制协议

报文格式(Message format)

所有字段以 Big Endian(大端序) 的方式存储。

字段描述

消息类型详细说明

目前所有TTS websocket请求都使用full client request格式，无论"query"还是"submit"。

Full client request

• Header size为b0001(即4B，没有header extension)。
• Message type为b0001.
• Message type specific flags固定为b0000.
• Message serialization method为b0001JSON。字段参考上方表格。
• 如果使用gzip压缩payload，则payload size为压缩后的大小。

Audio-only server response

• Header size应该为b0001.
• Message type为b1011.
• Message type specific flags可能的值有：
  • b0000 - 没有sequence number.
  • b0001 - sequence number > 0.
  • b0010orb0011 - sequence number < 0，表示来自服务器的最后一条消息，此时客户端应合并所有音频片段(如果有多条)。
• Message serialization method为b0000(raw bytes).

4.注意事项

• websocket单条链接仅支持单次合成，若需要合成多次，则需要多次建立链接
• 每次合成时reqid这个参数需要重新设置，且要保证唯一性（建议使用uuid.V4生成）
• operation需要设置为submit

5.Demo

python

tts_websocket_demo.py

6.89KB

Java

tts-demo-java.zip

7.01KB

Go

tts_websocket_demo.go

7.68KB

HTTP

使用账号申请部分申请到的appid&access_token进行调用
文本全部合成完毕之后，一次性返回全部的音频数据

1. 接口说明

接口地址为 https://openspeech.bytedance.com/api/v1/tts

2. 身份认证

认证方式采用 Bearer Token.
1)需要在请求的 Header 中填入"Authorization":"Bearer;${token}"

AppID/Token/Cluster 等信息可参考 控制台使用FAQ-Q1

3. 注意事项

• 使用 HTTP Post 方式进行请求，返回的结果为 JSON 格式，需要进行解析
• 因 json 格式无法直接携带二进制音频，音频经base64编码。使用base64解码后，即为二进制音频
• 每次合成时 reqid 这个参数需要重新设置，且要保证唯一性（建议使用 UUID/GUID 等生成）

4. Demo
   

Python

tts_http_demo.py

1.33KB

Java

tts_http_demo.zip

13.27KB

Go

tts_http_demo.go

3.44KB

参数说明

备注：

1. 支持ssml能力，参考SSML标记语言--语音技术-火山引擎 (volcengine.com)
2. 暂时不支持音高、音量调节
3. 支持中英混，支持语种自动识别

请求示例

{
    "app": {
        "appid": "appid123",
        "token": "access_token",
        "cluster": "volcano_icl"
    },
    "user": {
        "uid": "uid123"
    },
    "audio": {
        "voice_type": "S_xxxx",
        "encoding": "mp3",
        "speed_ratio": 1
    },
    "request": {
        "reqid": "uuid",
        "text": "字节跳动语音合成",
        "operation": "query"
    }
}

返回参数

响应示例

{
    "reqid": "reqid",
    "code": 3000,
    "operation": "query",
    "message": "Success",
    "sequence": -1,
    "data": "base64 encoded binary data",
    "addition": {
        "duration": "1960"
    }
}

返回码说明

常见错误返回说明

1. 错误返回：

   "message": "quota exceeded for types: xxxxxxxxx_lifetime"
   错误原因：试用版用量用完了，需要开通正式版才能继续使用

2. 错误返回：

"message": "quota exceeded for types: concurrency"
错误原因：并发超过了限定值，需要减少并发调用情况或者增购并发

3. 错误返回：

   "message": "Fail to feed text, reason Init Engine Instance failed"
   错误原因：voice_type / cluster 传递错误

4. 错误返回：

"message": "illegal input text!"
错误原因：传入的text无效，没有可合成的有效文本。比如全部是标点符号或者emoji表情，或者使用中文音色时，传递日语，以此类推。多语种音色，也需要使用language指定对应的语种

5. 错误返回：

"message": "authenticate request: load grant: requested grant not found"
错误原因：鉴权失败，需要检查appid&token的值是否设置正确，同时，鉴权的正确格式为
headers["Authorization"] = "Bearer;${token}"

API接入说明

访问鉴权

1. 鉴权方式说明 公共参数--API签名调用指南-火山引擎 (volcengine.com)

线上请求地址域名 open.volcengineapi.com

2. 固定公共参数

Region = "cn-north-1"
Service = "speech_saas_prod"
Version = "2023-11-07"
解释

3. AKSK获取 访问控制-火山引擎 (volcengine.com)

说明：Access Key（密钥）管理--API访问密钥（Access Key）-火山引擎 (volcengine.com)

4. 调用方式
   1. SDK SDK概览--API签名调用指南-火山引擎 (volcengine.com)
   2. 直接签名后调用

结合文档内api说明调用 ListMegaTTSTrainStatus 的例子(*其他语言和使用sdk调用的方式请参考火山鉴权源码说明 一)

3. 示例代码：

sign.go

未知大小

sign.py

未知大小

sign.java

未知大小

错误码

1. 非 2xx 开头的HTTP返回状态码被可以认为是错误
2. 错误的HTTP返回结构体如下

{
    "ResponseMetadata": 
    {
        "RequestId": "20220214145719010211209131054BC103", // header中的X-Top-Request-Id参数
        "Action": "ListMegaTTSTrainStatus",
        "Version": "2023-11-07",
        "Service": "{Service}",// header中的X-Top-Service参数
        "Region": "{Region}", // header中的X-Top-Region参数
        "Error": 
        {
            "Code": "InternalError.NotCaptured",
            "Message": "xxx"
        }
    }
}

3. "ResponseMetadata.Error.Code" 客户端可以依照这个字段判断错误种类，已知种类和含义如下

API列表

查询 SpeakerID 状态信息 ListMegaTTSTrainStatus

接口说明

查询已购买的音色状态信息，支持按SpeakerIDs和State过滤。
如果查询条件为空，返回账号的AppID下所有的列表（音色超过1000，强烈建议使用分页接口BatchListMegaTTSTrainStatus）。

请求方式

POST

请求参数

返回数据

{
          "ResponseMetadata": {
              "RequestId": "20220214145719010211209131054BC103", // header中的X-Top-Request-Id参数
              "Action": "",
              "Version": "",
              "Service": "{Service}",// header中的X-Top-Service参数
              "Region": "{Region}" // header中的X-Top-Region参数
          },
          "Result":{
                  "Statuses": [
                         {
                              "CreateTime": 1700727790000, // unix epoch格式的创建时间，单位ms
                              "DemoAudio": "https://example.com", // http demo链接
                              "InstanceNO": "Model_storage_meUQ8YtIPm", // 火山引擎实例number
                              "IsActivable": true, // 是否可激活
                              "SpeakerID": "S_VYBmqB0A", // speakerID
                              "State": "Success", // speakerID的状态
                              "Version": "V1", // speakerID已训练过的次数
                              "ExpireTime": 1732895999000, //过期时间
                              "Alias": "", //别名，和控制台同步
                              "AvailableTrainingTimes": 9 //剩余训练次数，激活音色为0
                        },
                        {
                              "SpeakerID": "S_VYBmqB0B", // speakerID
                              "State": "Unknown", // speakerID的状态
                        }
                  ]
          }
      }

分页查询SpeakerID状态 BatchListMegaTTSTrainStatus

接口说明

查询已购买的音色状态；相比ListMegaTTSTrainStatus 增加了分页相关参数和返回；支持使用token和声明页数两种分页方式；其中，

• 分页token在最后一页为空
• 分页token采用私有密钥进行加密
• 分页接口为新接口，不影响已有接口行为

请求方式

POST

请求参数

返回数据

{
    "ResponseMetadata": 
    {
        "RequestId": "20220214145719010211209131054BC103", // header中的X-Top-Request-Id参数
        "Action": "BatchListMegaTTSTrainStatus",
        "Version": "2023-11-07",
        "Service": "{Service}",// header中的X-Top-Service参数
        "Region": "{Region}" // header中的X-Top-Region参数},
        "Result":
        {
            "AppID": "xxx",
            "TotalCount": 2, // speakerIDs总数量
            "NextToken": "", // NextToken字符串，可发送请求后面的结果; 如果没有更多结果将为空
            "PageNumber": 1, // 使用分页参数时的当前页数
            "PageSize": 2, // 使用分页参数时当前页包含的条数
            "Statuses": 
            [
                {
                    "CreateTime": 1700727790000, // unix epoch格式的创建时间，单位ms
                    "DemoAudio": "https://example.com", // http demo链接
                    "InstanceNO": "Model_storage_meUQ8YtIPm", // 火山引擎实例Number
                    "IsActivable": true, // 是否可激活
                    "SpeakerID": "S_VYBmqB0A", // speakerID
                    "State": "Success", // speakerID的状态
                    "Version": "V1" // speakerID已训练过的次数
                },
                {
                    "SpeakerID": "S_VYBmqB0B", // speakerID
                    "State": "Unknown", // speakerID的状态
                    "Version": "V1" // speakerID已训练过的次数
                }
            ]
        }
}

附录

State状态枚举值