Websocket接口
最近更新时间：2024.03.12 11:30:04
首次发布时间：2021.12.20 14:44:12
此文档主要是说明TTS WebSocket接口如何调用。
1. 接口说明
接口地址为 wss://openspeech.bytedance.com/api/v1/tts/ws_binary
2. 身份认证
认证方式使用Bearer Token，在请求的header中加上"Authorization": "Bearer; {token}"，并在请求的json中填入对应的appid。
注意
Bearer和token使用分号 ; 分隔，替换时请勿保留{}
AppID/Token/Cluster 等信息可参考 控制台使用FAQ-Q1
3. 请求方式
3.1 二进制协议
报文格式(Message format)
所有字段以 Big Endian(大端序) 的方式存储。
字段描述
| 字段 Field (大小, 单位bit) | 描述 Description | 值 Values |
|---|---|---|
| 协议版本(Protocol version) (4) | 可能会在将来使用不同的协议版本，所以这个字段是为了让客户端和服务器在版本上保持一致。 | 0b0001 - 版本 1 (目前只有版本1) |
| 报头大小(Header size) (4) | header实际大小是 header size value x 4 bytes. 这里有个特殊值 0b1111 表示header大小大于或等于60(15 x 4 bytes)，也就是会存在header extension字段。 | 0b0001 - 报头大小 = 4 (1 x 4) 0b0010 - 报头大小 = 8 (2 x 4) 0b1010 - 报头大小 = 40 (10 x 4) 0b1110 - 报头大小 = 56 (14 x 4) 0b1111 - 报头大小为60或更大; 实际大小在header extension中定义 |
| 消息类型(Message type) (4) | 定义消息类型。 | 0b0001 - full client request. ~~0b1001~~ 0b1011 - Audio-only server response (ACK). 0b1111 - Error message from server (例如错误的消息类型，不支持的序列化方法等等) |
| Message type specific flags (4) | flags含义取决于消息类型。 具体内容请看消息类型小节. | |
| 序列化方法(Message serialization method) (4) | 定义序列化payload的方法。 注意：它只对某些特定的消息类型有意义 (例如Audio-only server response 0b1011 就不需要序列化). | 0b0000 - 无序列化 (raw bytes) 0b0001 - JSON 0b1111 - 自定义类型, 在header extension中定义 |
| 压缩方法(Message Compression) (4) | 定义payload的压缩方法。 Payload size字段不压缩(如果有的话，取决于消息类型)，而且Payload size指的是payload压缩后的大小。 Header不压缩。 | 0b0000 - 无压缩 0b0001 - gzip 0b1111 - 自定义压缩方法, 在header extension中定义 |
| 保留字段(Reserved) (8) | 保留字段，同时作为边界 (使整个报头大小为4个字节). | 0x00 - 目前只有0 |
消息类型详细说明
目前所有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).
3.2 参数说明
参考文档：参数基本说明
注意事项
- websocket单条链接仅支持单次合成，若需要合成多次，则需要多次建立链接
- 每次合成时reqid这个参数需要重新设置，且要保证唯一性（建议使用uuid.V4生成）
- operation需要设置为submit
Demo
python
Java
Go