You need to enable JavaScript to run this app.
导航
大模型语音合成双向流式API
最近更新时间:2024.09.19 21:36:56首次发布时间: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

Yes

volc.service_type.10029

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过滤

bool

true

示例:

{
    "user": {
        "uid": "12345"
    },
    "event": 100,
    "req_params": {
        "text": "明朝开国皇帝朱元璋也称这本书为,万物之根",
        "speaker": "zh_female_baoqingfangzhu",
        "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 返回句的音频内容

数据类

下行

交互示例

图片

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
未知大小