本方案是基于 WebSocket 协议的接入方式，主要包括四个阶段：连接的建立、会话的创建、持续的交互以及连接的断开。
用于设备长时间保持连接的场景，支持一个连接多次交互，以及全双工交互。注意：该接口仅支持同一个设备（auth_id）保持一个连接，新连接建立会断开当前设备已经存在的连接。
WebSocket握手阶段主要用于业务参数声明和权限校验，参数在握手请求的url中指定，握手请求和参数必须符合WebSocket协议规范。
ws[s]://staging-api.listenai.com/v1/interaction
请求示例：
ws[s]://staging-api.listenai.com/v1/interaction?apikey=xxx¶m=xxx
请求参数详细说明：
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| apikey | string | 是 | 产品的云云对接密钥 | e9c0794c-30b9-44e3-8810-xxxxxxxxxx |
| param | string | 是 | 相关参数 JSON 串经 Base64 编码后的字符串，详见 param 字段说明 | ewoJImF1dGhfaWQiOiJMUzIwMjQwMzI2MDAzIgp9 |
param 为相关参数 JSON 串经 Base64 编码后的字符串，原始json字段说明如下：
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| auth_id | string | 是 | 用户唯一ID（即对应device_id） | LS20240326003 |
param生成示例：
// 原始JSON串：
{
"auth_id":"LS20240326003"
}
// BASE64编码：
ewoJImF1dGhfaWQiOiJMUzIwMjQwMzI2MDAzIgp9
成功：
{
"action":"connected",
"cid":"cidf415ba9c@dx8d0d18b0d6dd3eef00",
"code":"0",
"data":"",
"desc":"success"
}
失败：
{
"action": "error",
"cid": "3def61d96bdd",
"code": "400",
"data": "",
"desc": "设备在其他地方上线"
}
WebSocket 进入实时通信阶段，可以进行会话的创建、数据的上传、结果的接收等。
整体的交互协议分为指令和数据，分别对应TEXT消息和BINARY消息。
连接建立之后，就可以开始创建会话，创建会话是为了在长连接中标识一次会话请求的起点，定义BINARY消息类型(如文本数据和音频数据)、需要的结果类型和各类型的参数。创建会话之后，在会话结束之前，所有请求的数据和指令均属于该会话。
{
"action":"start",
"params":{
"data_type":"audio",
"aue":"raw",
"features":[]
}
}
参数说明
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| action | string | 是 | 指令类型 | start |
| params | object | 是 | 业务参数 | |
| params.fullduplex | string | 否 | 是否开启全双工："1"（开启）、"2"（关闭），默认关闭 | "1" |
| params.data_type | string | 是 | 数据类型：audio、text | audio |
| params.aue | string | 是 | 数据类型为audio时必填，指定音频格式： 【默认】raw: pcm格式(16khz 16bit LE, 单声道) opus-wb: opus-wb格式 speex-wb: speex-wb格式 ico: ico格式 |
raw |
| params.speex_size | int | 否 | 音频数据格式为speex-wb时必填 | 70 |
| features | array | 是 | 只需要asr结果时，传空数组 | |
| params.asr_properties | object | 否 | 设备端指定的asr参数，详见asr_properties参数说明 |
asr_properties参数说明
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| asr_appid | string | 否 | 自定义appid，一般不使用 | |
| asr_apikey | string | 否 | 自定义apikey，一般不使用 | |
| asr_apisecret | string | 否 | 自定义apisecret，一般不使用 | |
| evad | string | 否 | 是否开启LS Gateway提供的vad "1": 开启 "0": 关闭 |
"1" |
| vad_eos | int | 否 | vad后端点 | 800 |
| ent | string | 否 | 设备端指定的识别引擎 | home-va |
会话创建帧响应
会话创建成功后，云端会返回以下响应：
{
'action':'started',
'cid': 'ee60b72f0ec7',
'code':'0',
'data':'',
'desc':'success',
'fid': 'f79a8ef4307d',
'sid':'33737e7ce2f74497baa2ee51b344df8a'
}
设备端上传数据有两种方式，文本数据和音频数据。在交互过程中，设备端不断构造 binary message 发送到服务端，内容是音频或文本的二进制数据。一个会话中，二进制文本数据只需要发送一次。
客户端可以主动结束音频发送，云端会结束识别并进行对应的处理。指令内容如下：
{
"action": "end"
}
参数说明
| 参数 | 类型 | 说明 | 必须 |
|---|---|---|---|
| action | string | 状态标识(类型详见action参数说明) | 是 |
| code | string | 云端返回编码 | 是 |
| cid | string | 云端当前长连接id | 否 |
| fid | string | 云端单次全双工交互id | 否 |
| sid | string | 云端单次交互id(可用于查询交互记录) | 是 |
action参数说明
| 参数 | 类型 | 说明 | 必须 |
|---|---|---|---|
| started | string | 会话创建状态标识 | 是 |
| result | string | 识别结果返回状态标识 | 是 |
| finish | string | 会话结束状态标识 | 是 |
data参数说明
| 参数 | 类型 | 说明 | 必须 |
|---|---|---|---|
| sub | string | 详见sub状态结果 | 是 |
| is_last | bool | 是否是最后识别结果(详见is_last参数说明) | 是 |
| code | string | 云端返回编码 | 是 |
| auth_id | string | 是 | |
| result_id | int | 是 |
sub参数说明
| 参数 | 类型 | 说明 | 必须 |
|---|---|---|---|
| iat | string | 识别结果 | 是 |
| vad | string | vad结果（注：vad结果可能会在最终识别结果前下发） | 是 |
| tts | string | tts结果 | 是 |
| nlp | string | 语义结果 | 是 |
is_last参数说明
| 参数 | 类型 | 说明 | 必须 |
|---|---|---|---|
| True | string | 是最后识别结果 | 是 |
| False | string | 非最后识别结果 | 是 |
识别结果(流式)
{
'code': '0',
'data': {
'sub': 'iat',
'is_last': True,
'auth_id': 'd9ec6e29f379cf919d9daed0d2459612',
'result_id': 5,
'text': '今天广州的天气怎么样？需要带伞吗？？'
},
'action': 'result',
'desc': 'success',
'sid': '5404f85784014c068bdc8a90a66d3d4a',
'fid': '10f3eca6a9c5',
'cid': 'ee60b72f0ec7'
}
vad结果（注：vad结果可能会在最终识别结果前下发，表示静音段超过eos，请设备端停止录音）
{
'code': '0',
'data': {
'sub': 'vad',
'result_id': 0,
'info': 'end'
},
'action': 'result',
'desc': 'success',
'sid': '5404f85784014c068bdc8a90a66d3d4a',
'fid': '10f3eca6a9c5',
'cid': 'ee60b72f0ec7'
}
python：
python-ws.zip