双向流式API-支持复刻2.0--语音技术-火山引擎

文档中心

导航

双向流式API-支持复刻2.0

最近更新时间：2024.12.16 17:51:22首次发布时间：2024.08.09 17:33:59

1 接口功能

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

1.1 最佳实践

该接口会处理碎片化的文本或者过长的文本，整理为长度合适的句子。因此最大的优势是平衡延迟和合成效果。
在对接大文本模型时，推荐将流式输出的文本直接输入该接口，而不要额外增加切句或者攒句的逻辑。同样的文本调用一次该接口与多次调用合成接口相比，前者会更为自然，情绪更饱满。
该接口每次使用均需要建立websocket连接，发送start connection，发送start session，通过task request发送文本，同时接收音频。在没有文本可以发送后，需立即发送finish session。多数情况下此时音频还未完全返回完毕，具体流程可参考该页交互示例。

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-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（主要针对文本类型消息）
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服务参数具体如下，大部分设置仅在StartSession生效，每次发送的文本可在TaskRequest中生效

字段	描述	是否必须	类型	默认值
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 类	上行
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(`2`)		len(`<payload_json>`)
12 - 93	`{}`		`payload_json` 扩展保留，暂留空JSON

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(`2`)		len(`payload_json`)
12-13	`{}`		`payload_json` 扩展保留，暂留空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(`2`)		len(`payload_json`)
23 - 24	`{}`		`payload_json` 扩展保留，暂留空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(`2`)		len(`payload_json`)
28 - 29	`{}`		`payload_json` 扩展保留，暂留空JSON

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(`2`)		len(`payload_json`)
28 - 29	`{}`		`payload_json` 扩展保留，暂留空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(`<payload_json>`)
28 - ...	`{...}`		`payload_json`

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

未知大小

Java:

TTSWebsocketDemo.java

未知大小