导航
公共协议-WebSocket
最近更新时间：2023.05.19 16:19:13首次发布时间：2021.12.14 20:44:27
接口说明
请求地址
部分音频能力支持通过WebSocket API的方式提供流式的调用，请求地址：ws[s]://sami.bytedance.com。
服务支持HTTPS访问，考虑到数据安全，强烈推荐使用协议 wss。
请求参数
请求中不同消息类型的发送：
- Text messge文本消息类型，包含控制事件和请求参数
- Binary message二进制消息类型，发送 只包含二进制数据 的请求
其中文本消息类型请求的定义如下：
| 字段 | 描述 | 类型 | 是否必填 | 默认值 |
|---|---|---|---|---|
| token | 服务鉴权token | string | 是 | - |
| appkey | 服务接入appkey。在音频技术控制台创建应用后获得 | string | 是 | - |
| namespace | 服务接口命名空间，比如TTS | string | 是 | - |
| event | 服务请求任务事件，比如StartTask。详见事件类型 | string | 是 | - |
| data | 服务请求二进制数据，比如音频二进制数据，标准base64编码 | string | 否 | - |
| payload | 服务请求配置参数，比如音频编码信息等。具体填写要求详见对应API接口说明文档 | string | 否 | - |
备注：
- 为了节省链路开销，当payload为空时，请求的二进制数据通过二进制消息类型发送
响应格式
响应中不同消息类型的接收：
- Text message文本消息类型，包含控制事件和响应数据
- Binary message二进制消息类型，接收 只包含二进制数据 的响应
其中文本消息类型响应的定义如下：
| 字段 | 描述 | 类型 |
|---|---|---|
| task_id | 请求任务id，用于链路追踪、问题排查 | string |
| message_id | 请求任务消息id，用于链路追踪、问题排查 | string |
| namespace | 服务接口命名空间，比如TTS | string |
| event | 服务请求任务事件，比如StartTask。详见事件类型 | string |
| data | 请求响应二进制数据，标准base64编码 | string |
| payload | 请求响应文本信息，json字符串格式。详见具体API接口说明文档 | string |
| status_code | 状态码。详见服务状态码 | number |
| status_text | 状态码。详见服务状态码 | string |
备注：
- 当返回响应既包含payload信息、又包含data信息时，响应通过文本消息类型返回，二进制数据通过标注base编码放入data字段
- 为了节省链路开销，当payload为空时，响应的二进制数据通过二进制消息类型返回
事件类型
任务开始事件
StartTask，客户端 -> 服务端任务成功开始事件
TaskStarted，服务端 -> 客户端，客户端在双向流式调用场景收到该事件后可以进行后续请求发送任务请求事件
TaskRequest，客户端 -> 服务端，若只包含二进制数据可以省略任务响应事件
TaskResponse，服务端 -> 客户端，若只包二进制数据可以省略任务完成事件
FinishTask，客户端 -> 服务端，客户端发送该事件表明请求数据发送完成任务成功事件
TaskFinished，服务端 -> 客户端，服务端发送该事件表明请求成功任务失败事件
TaskFailed，服务端 -> 客户端，服务端发送该事件表明请求失败
交互逻辑
使用上述事件进行交互，可以实现实现双向流式调用和服务端流式调用。
备注：
TaskRequest和TaskResponse，若 只包含二进制数据 则简化为BinaryMessage进行传输
双向流式
服务端流式
