You need to enable JavaScript to run this app.
导航
语音技术
  • 文档首页
    • /语音技术/开发参考/语音合成大模型/双向流式API-支持复刻2.0
双向流式API-支持复刻2.0
最近更新时间：2024.11.05 17:48:09首次发布时间：2024.08.09 17:33:59
我的收藏

1 接口功能

双向流式API为用户提供文本转语音能力，支持多语种、多方言，支持WebSocket协议流式调用，同时支持一包发送请求数据或者边发边收数据的流式交互方式。

2 接口说明

2.1 请求Request

请求路径

  • 服务使用的请求路径：wss://openspeech.bytedance.com/api/v3/tts/bidirection

建连&鉴权

  • 在 websocket 建连的 HTTP 请求头（Request Header 中）添加以下信息

Key

说明

是否必须

Value 示例

X-Api-App-Key

使用火山引擎控制台获取的APP ID，可参考 控制台使用FAQ-Q1

Yes

123456789

X-Api-Access-Key

使用火山引擎控制台获取的Access Token，可参考 控制台使用FAQ-Q1

Yes

your-access-key

X-Api-Resource-Id

表示调用服务的资源信息 ID

  • 大模型语音合成：volc.service_type.10029
  • 声音复刻2.0：volc.megatts.default

Yes

  • 大模型语音合成：volc.service_type.10029
  • 声音复刻2.0：volc.megatts.default

（不支持声音复刻1.0）

X-Api-Request-Id

用于追踪当前调用信息的标志 ID

Yes

67ee89ba-7050-4c04-a3d7-ac61a63499b3

X-Api-Connect-Id

用于追踪当前连接情况的标志 ID
建议用户传递，便于排查连接情况

67ee89ba-7050-4c04-a3d7-ac61a63499b3

  • 在 websocket 握手成功后，会返回这些 Response header

Key

说明

Value 示例

X-Tt-Logid

服务端返回的 logid，建议用户获取和打印方便定位问题

202407261553070FACFE6D19421815D605

WebSocket 二进制协议

WebSocket 使用二进制协议传输数据。
协议的组成由至少 4 个字节的可变 header、payload size 和 payload 三部分组成，其中

  • header 描述消息类型、序列化方式以及压缩格式等信息
  • 可选字段
    • event 字段，用于描述连接过程中状态管理的预定义事件
    • connect id size/ connect id 字段，用于描述连接类事件的额外信息
    • session id size/ session id 字段，用于描述会话类事件的额外信息
    • error code: 仅用于错误帧，描述错误信息
  • payload size 是 payload 的长度
  • payload 是具体负载内容，依据消息类型不同 payload 内容不同。

需注意：协议中整数类型的字段都使用大端表示。

二进制帧

Byte

Left 4-bit

Right 4-bit

说明

0 - Left half

Protocol version

目前只有v1，始终填0b0001

0 - Right half

Header size (4x)

目前只有4字节，始终填0b0001

1

Message type

Message type specific flags

下文详细说明

2 - Left half

Serialization method

  • 0b0000：Raw（无特殊序列化方式，主要针对二进制音频数据）
  • 0b0001：JSON（主要针对文本类型消息）
  • 0b0010：Protobuf（如非必要，暂不使用）
  • 0b0011：Thrift（如非必要，暂不使用）

2 - Right half

Compression method

  • 0b0000：无压缩
  • 0b0001：gzip

3

Reserved

留空（0b0000 0000）

[4 ~ 7]

[Optional field,like event number,...]

取决于Message type specific flags，可能有、也可能没有

...

Payload

可能是音频数据、文本数据、音频文本混合数据

Message type & specific flags

Message type & specific flags是重点扩展的部分，详细说明如下：

Message type

含义

Message type specific flags

是否包含Event number

备注

0b0001

Full-client request

0b0100

是

完整请求体，用于触发服务端session初始化

0b1001

Full-server response

0b0100

是

TTS：前端信息、文本音频混合数据等（Serialization=JSON）

0b1011

Audio-only response

0b0100

是

0b1111

Error information

None

否

Payload 请求参数

TTS服务参数具体如下

字段

描述

是否必须

类型

默认值

user

用户信息

user.uid

用户uid

event

请求的事件

√

namespace

请求方法

string

BidirectionalTTS

req_params.text

required，输入文本，与ssml字段至少一个非空，若ssml非空则按照ssml字段

√

string

req_params.speaker

发音人，具体见发音人列表

√

string

req_params.audio_params

音频参数，便于服务节省音频解码耗时

√

object

req_params.audio_params.format

音频编码格式，mp3/ogg_opus/pcm

string

mp3

req_params.audio_params.sample_rate

音频采样率，可选值 [8000,16000,22050,24000,32000,44100,48000]

number

24000

req_params.audio_params.speech_rate

语速，取值范围[-50,100]，100代表2.0倍速，-50代表0.5倍数

number

0

req_params.audio_params.pitch_rate

音调，取值范围[-12,12]

number

0

req_params.audio_params.enable_timestamp

是否选择同时返回字与音素时间戳

bool

false

req_params.additions

用户自定义参数

jsonstring

req_params.additions.enable_language_detector

自动识别语种

bool

false

req_params.additions.disable_markdown_filter

是否关闭markdown过滤，true为不过滤，false为过滤

bool

true

req_params.additions.enable_latex_tn

是否可以播报latex公式，需将disable_markdown_filter设为true

bool

false

req_params.additions.max_length_to_filter_parenthesis

是否过滤括号内的部分，0为不过滤，100为过滤

int

100

示例:

{
    "user": {
        "uid": "12345"
    },
    "event": 100,
    "req_params": {
        "text": "明朝开国皇帝朱元璋也称这本书为,万物之根",
        "speaker": "zh_female_shuangkuaisisi_moon_bigtts",
        "audio_params": {
            "format": "mp3",
            "sample_rate": 24000
        },
      }
    }
}

2.2 响应Response

建连响应

主要关注建连阶段 HTTP Response 的状态码和 Body

  • 建连成功：状态码为 200
  • 建连失败：状态码不为 200，Body 中提供错误原因说明

WebSocket 传输响应

文本帧

  • 主要通过文本内容反馈异常错误信息

二进制帧

  • 主要通过协议约定的方式，结构化返回正常响应和一般错误信息

正常响应帧

Byte

Left 4-bit

Right 4-bit

说明

0 - Left half

Protocol version

目前只有v1，始终填0b0001

0 - Right half

Header size (4x)

目前只有4字节，始终填0b0001

1

Message type

Message type specific flags

下文详细说明

2 - Left half

Serialization method

  • 0b0000：Raw（无特殊序列化方式，主要针对二进制音频数据）
  • 0b0001：JSON（主要针对文本类型消息）
  • 0b0010：Protobuf（如非必要，暂不使用）
  • 0b0011：Thrift（如非必要，暂不使用）

2 - Right half

Compression method

  • 0b0000：无压缩
  • 0b0001：gzip

3

Reserved

留空（0b0000 0000）

[4 ~ 7]

[Optional field,like event number,...]

取决于Message type specific flags，可能有、也可能没有

...

Payload

可能是音频数据、文本数据、音频文本混合数据

Payload 响应参数

字段

描述

类型

默认值

data

返回的二进制数据包

[]byte

event

返回的事件类型

number

res_params.text

经文本分句后的句子

string

res_params.duration

该句文本的音频时长

number

错误响应帧

Byte

Left 4-bit

Right 4-bit

说明

0 - Left half

Protocol version

目前只有v1，始终填0b0001

0 - Right half

Header size (4x)

目前只有4字节，始终填0b0001

1

Message type

Message type specific flags

固定为 0b11110000

2 - Left half

Serialization method

  • 0b0001：JSON（主要针对文本类型消息）

2 - Right half

Compression method

  • 0b0000：无压缩

3

Reserved

留空（0b0000 0000）

[4 ~ 7]

Error code

错误码

...

Payload

错误消息对象

2.3 Event 定义

在 TTS 场景中，Event 是正常数据帧（包括上行和下行）的必要字段，事件定义了请求过程中必要的状态转移。具体的使用过程详见交互示例部分

Event code

含义

事件类型

应用阶段：上行/下行

1

StartConnection，Websocket 阶段申明创建连接
（在 HTTP 建连 Upgrade 后）

Connect 类

上行

2

FinishConnection，结束连接

Connect 类

下行

50

ConnectionStarted，成功建连

Connect 类

下行

51

ConnectionFailed，建连失败

Connect 类

下行

52

ConnectionFinished 结束连接成功

Connect 类

下行

100

StartSession，Websocket 阶段申明创建会话

Connect 类

上行

101

CancelSession，声明取消会话（上行&下行）

Session 类

上行

102

FinishSession，声明结束会话（上行）

Session 类

上行

150

SessionStarted，成功开始会话

Session 类

下行

151

SessionCanceled，已取消会话

Session 类

下行

152

SessionFinished，会话已结束（上行&下行）

Session 类

下行

153

SessionFailed，会话失败

Session 类

下行

200

TaskRequest，传输请求内容

数据类

上行

350

TTSSentenceStart，TTS 返回句内容开始

数据类

下行

351

TTSSentenceEnd，TTS 返回句内容结束

数据类

下行

352

TTSResponse，TTS 返回句的音频内容

数据类

下行

交互示例

Image

Connection 类：

  • StartConnection包（RequestMeta）：

Byte

Left 4-bit

Right 4-bit

备注

0

0001

0001

v1

4-byte header

1

0001

0100

Full-client request

with event number

2

0001

0000

JSON

no compression

3

0000

0000

4 - 7

int32(Event_StartConnection)

event type

8 - 11

uint32(82)

len(<request_meta_json>)

12 - 93

{}

扩展保留

  • FinishConnection包（RequestMeta）：

Byte

Left 4-bit

Right 4-bit

备注

0

0001

0001

v1

4-byte header

1

0001

0100

Full-client request

with event number

2

0001

0000

JSON

no compression

3

0000

0000

4 - 7

int32(Event_FinishConnection)

event type

8-11

uint32(...)

len(min_payload)

12-13

{}

最小 JSON

  • ConnectionStarted包：

Byte

Left 4-bit

Right 4-bit

备注

0

0001

0001

v1

4-byte header

1

1001

0100

Full-server response

with event number

2

0001

0000

JSON

no compression

3

0000

0000

4 - 7

int32(Event_ConnectionStarted)

event type

8 - 11

uint32(7)

len(<connection_id>)

12 - 18

bxnweiu

connection_id

19 - 22

uint32(...)

len(min_payload)

23 - 24

{}

最小 JSON

允许客户端不填connection_id，由网关下发一个唯一的ID

  • ConnectionFailed包（ResponseMeta）：

Byte

Left 4-bit

Right 4-bit

备注

0

0001

0001

v1

4-byte header

1

1001

0100

Full-server response

with event number

2

0001

0000

JSON

no compression

3

0000

0000

4 - 7

int32(Event_ConnectionFailed)

event type

8 - 11

uint32(7)

len(<connection_id>)

12 - 15

uint32(58)

len(<response_meta_json>)

16 - 73

{
  "status_code": 4xxxxxxx,
  "message": "unauthorized"
}

response_meta_json

  • 既可能是客户端错误，又可能是服务端错误
  • 仅含status_code和message字段

Session 类：

  • StartSession包（RequestMeta）：

Byte

Left 4-bit

Right 4-bit

备注

0

0001

0001

v1

4-byte header

1

0001

0100

Full-client request

with event number

2

0001

0000

JSON

no compression

3

0000

0000

4 - 7

int32(Event_StartSession)

event type

8 - 11

uint32(12)

len(<session_id>)

12 - 23

nxckjoejnkegf

session_id

24 - 27

uint32(...)

len(tts_session_meta)

28 - ...

{
  "user": ...,
  "req_params": ...
}

tts_session_meta

不允许客户端不填session_id

  • FinishSession包（RequestMeta）：

Byte

Left 4-bit

Right 4-bit

备注

0

0001

0001

v1

4-byte header

1

0001

0100

Full-client request

with event number

2

0001

0000

JSON

no compression

3

0000

0000

4 - 7

int32(Event_FinishSession)

event type

8 - 11

int32(12)

len(<session_id>)

12 - 23

nxckjoejnkegf

session_id

24 - 27

uint32(...)

len(min_payload)

28 - 29

{}

最小 JSON

  • CancelSession包（RequestMeta）：与FinishSession类似
  • SessionStarted包（ResponseMeta）：

Byte

Left 4-bit

Right 4-bit

备注

0

0001

0001

v1

4-byte header

1

1001

0100

Full-server response

with event number

2

0001

0000

JSON

no compression

3

0000

0000

4 - 7

int32(Event_SessionStarted)

event type

8 - 11

uint32(12)

len(<session_id>)

12 - 23

nxckjoejnkegf

session_id

24 - 27

uint32(...)

len(min_payload)

28 - 29

{}

最小 JSON

  • SessionFinished包（ResponseMeta）：

Byte

Left 4-bit

Right 4-bit

备注

0

0001

0001

v1

4-byte header

1

1001

0100

Full-server response

with event number

2

0001

0000

JSON

no compression

3

0000

0000

4 - 7

int32(Event_SessionFinished)

event type

8 - 11

uint32(12)

len(<session_id>)

12 - 23

nxckjoejnkegf

session_id

24 - 27

uint32(48)

len(<response_meta_json>)

28 - 75

{
  "status_code": 20000000,
  "message": "ok"
}

response_meta_json

  • 仅含status_code和message字段
  • SessionFailed包（ResponseMeta）：与SessionFinished类似
  • SessionCanceled包（ResponseMeta）：与SessionFinished类似

数据类：

  • 音频，含Event（以上行Event_TaskRequest事件为例）：

Byte

Left 4-bit

Right 4-bit

备注

0

0001

0001

v1

4-byte header

1

0010

0100

Audio-only request

with event number

2

0000

0000

raw

no compression

3

0000

0000

4 - 7

int32(Event_TaskRequest)

event type

8 - 11

uint32(12)

len(<session_id>)

12 - 23

nxckjoejnkegf

session_id

24 - 27

uint32(...)

len(<audios_binary>)

28 - ...

...

audio_binary

  • 音频，不含Event（以上行音频为例）：

Byte

Left 4-bit

Right 4-bit

备注

0

0001

0001

v1

4-byte header

1

0010

0000

Audio-only request

no event number

2

0000

0000

raw

no compression

3

0000

0000

8 - 11

uint32(12)

len(<session_id>)

12 - 23

nxckjoejnkegf

session_id

24 - 27

uint32(...)

len(<audios_binary>)

28 - ...

...

audio_binary

  • 文本，含Event（以上行Event_TaskRequest事件为例）：

Byte

Left 4-bit

Right 4-bit

备注

0

0001

0001

v1

4-byte header

1

0001

0100

Full-client request

with event number

2

0001

0000

JSON

no compression

3

0000

0000

4 - 7

int32(Event_TaskRequest)

event type

8 - 11

uint32(12)

len(<session_id>)

12 - 23

nxckjoejnkegf

session_id

24 - 27

uint32(...)

len(<JSON_text>)

28 - ...

{...}

JSON_text

4 错误码

新框架错误码

CodeOK Code = 20000000 //成功
CodeClientError Code = 45000000 //客户端通用错误
CodeServerError Code = 55000000 //服务端通用错误
CodeSessionError      Code = 55000001 //服务端session错误
CodeInvalidReqError   Code = 45000001 //客户端请求参数错误

示例Samples

Go:

将下面两行替换为控制台获取的APP ID和Access Token

appKey     = flag.String("app_key", "your_app_key", "VolcEngine app ID")
accessKey  = flag.String("access_key", "your_access_key", "Access Token for authorization")
bidirectional_tts.zip
未知大小