当前 ASR 单点能力基于端云协议实现，如需实现 ASR、LLM、TTS 端云全链路功能，请参考端云交互链路协议
ASR(v2) 接口是基于 WebSocket 协议实现的实时语音识别服务，支持实时音频数据上传和识别结果返回。
本接口基于 WebSocket 协议实现数据传输，支持实时双向通信。
ws[s]://api.listenai.com/v2/asr
请求时需要在 HTTP Headers 中携带认证信息：
Authorization: Bearer {token}
Token 获取方式：
请在聆听平台获取。
请求示例：
ws[s]://api.listenai.com/v2/asr
成功响应：
{
"action": "connected",
"cid": "cidf415ba9c@dx8d0d18b0d6dd3eef00",
"code": "0",
"data": "",
"desc": "success"
}
失败响应：
{
"action": "error",
"cid": "cidf415ba9c@dx8d0d18b0d6dd3eef00",
"code": "11101",
"data": "",
"desc": "error desc"
}
响应字段说明：
| 字段 | 类型 | 说明 |
|---|---|---|
| action | string | 操作类型：connected（成功）/ error（失败） |
| cid | string | 连接 ID |
| code | string | 状态码：0 表示成功，其他表示错误 |
| data | string | 响应数据 |
| desc | string | 描述信息 |
WebSocket 连接建立之后，进入实时通信阶段，可以进行会话的创建、数据的上传、结果的接收等操作。
通信协议：
连接建立之后，可以开始创建会话。创建会话是为了在长连接中标识一次会话请求的起点，创建会话之后，在会话结束之前，所有请求的数据和指令均属于该会话。
请求示例：
{
"action": "start",
"params": {
"data_type": "audio",
"aue": "raw",
"asr_properties": {},
"wake_properties": {
"words": []
},
"vpr_properties": {}
}
}
参数说明：
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| action | string | 是 | 指令类型 | start |
| params | object | 是 | 业务参数 | |
| params.data_type | string | 是 | 数据类型：audio |
audio |
| params.aue | string | 是 | 音频编码格式： - raw: PCM 数据，格式 16khz 16bit LE，单声道- speex: speex 格式- speex-wb: speex-wb 格式- ico: ico 格式 |
raw |
| params.speex_size | int | 否 | 音频数据格式为 speex、speex-wb 时必填 | 70 |
| params.fullduplex | string | 否 | 是否开启连续识别模式：1 开启，0 关闭 |
1 |
| params.fullduplex_timeout | int | 否 | 连续识别模式下，持续无识别超时断开时间，默认60s | 60 |
| params.asr_properties | object | 否 | ASR 识别相关参数 | 见下方说明 |
| params.vad_properties | object | 否 | VAD（语音活动检测）相关参数 | 见下方说明 |
| params.wake_properties | object | 否 | 唤醒相关参数 | 见下方说明 |
| params.vpr_properties | object | 否 | 声纹识别相关参数 | 见下方说明 |
asr_properties 参数说明：
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| ent | string | 否 | 识别引擎 | |
| dwa | string | 否 | 开启实时返回识别结果功能："wpgs" 开启，"none" 关闭，默认开启 |
"wpgs" |
| dhw | string | 否 | 会话级个性化热词，参数长度不超过 1024 字节 | "dhw=utf-8;你好|大家" |
| ptt | int | 否 | 是否开启标点符号添加：1 开启，0 关闭，默认开启 |
1 |
vad_properties 参数说明：
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| vad_type | string | 否 | VAD 类型： - "default": 默认 VAD 引擎- "evad": 多维度 VAD 引擎默认为 "default" |
"default" |
| vad_eos | int | 否 | VAD 后端点，默认：500 | 500 |
| max_eos | int | 否 | 语义的最大 eos，若后端点出现后没检测出语义完整，超过 max_eos 退出，默认：1000 | 1000 |
| audio_gain | string | 否 | 只在 evad 下生效，音频增益数值，默认："1.0"，通常在录音音频增益幅值较低时，可适当调整。 |
"1.0" |
| vpr_verify | boolean | 否 | 只在 evad 下生效，声纹校验，默认为 false，当开启时，需要带上 vpr_properties 对应参数 |
false |
| vpr_type | string | 否 | 只在 evad 下生效，声纹校验类型： - "registered": 预注册声纹- "realtime":实时注册声纹默认为 "registered"。设置vpr_verify为true时生效 注意: realtime类型下，需要开启连续对话模式，且不支持设置vpr_properties.audio |
"registered" |
| max_bos | int | 否 | 只在 evad 下生效，最大 bos，超过则前端点超时退出，默认：5000 | 5000 |
| maybe_eos | int | 否 | 只在 evad 下生效，若后端点出现后检测出语义为 maybe，超过 maybe_eos 退出，默认：500 | 500 |
wake_properties 参数说明：
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| wake_words_filter | boolean | 否 | 识别结果对唤醒词过滤，默认为 false |
true |
| words | array | 否 | 唤醒词列表 | ["唤醒词1", "唤醒词2"] |
vpr_properties 参数说明：
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| audio | object | 否 | 目标音频 | |
| audio.audio_data | string | 是 | base64 编码的音频数据 | |
| audio.aue | string | 是 | 编码格式（pcm、lame、ico） | |
| feature_id | string | 否 | 声纹特征 ID | |
| group_id | string | 否 | 声纹特征库 ID | |
| speaker_threshold | double | 否 | 声纹识别阈值，默认0.25，使用实时注册声纹时，建议阈值为0.4 | 0.25 |
frame_properties 参数说明：
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| frame_size | int | 否 | 客户端发送的音频每帧websocket二进制数据长度，单位字节 | 40 |
| frame_ms | int | 否 | 客户端发送的音频每帧websocket二进制数据对应的时长，单位ms | 20 |
注意：
group_id、feature_id的来源可参考声纹特征管理文档audio_data、group_id、feature_id三者均能同时生效- 音频数据格式需要为 16k 16bit 1ch 的音频数据
- 当vpr_verify为
false或开启实时注册声纹(vpr_verify为true且vpr_type为realtime)时，若请求参数中包含feature_id或group_id，则会根据匹配的声纹信息返回声纹结果- 当
vad_type为evad且frame_properties.frame_size和frame_properties.frame_ms有设置时，vad的bos和eos信息会返回音频时间点
在交互过程中，客户端需要不断构造 binary message 发送到服务端，内容是音频二进制数据。
上传要求：
aue 参数）进行编码客户端可以主动结束音频发送，云端会结束识别并进行对应的处理。
请求示例：
{
"action": "end"
}
服务端会在不同阶段返回不同类型的结果，通过 action 字段区分消息类型。
会话创建成功：
{
"code": "0",
"data": "",
"action": "started",
"desc": "success",
"sid": "05f6a28a-718e-40dc-9f68-d62cf3c02271"
}
识别结果：
{
"code": "0",
"data": {
"sub": "iat",
"is_last": true,
"auth_id": "4d0c4412769b62f0f44134ce9f2db11f",
"result_id": 17,
"text": "今天广州的天气怎么样？需要带伞吗？"
},
"action": "result",
"desc": "success",
"sid": "05f6a28a-718e-40dc-9f68-d62cf3c02271"
}
识别结果字段说明：
| 字段 | 类型 | 说明 |
|---|---|---|
| sub | string | 结果类型："iat" 表示识别结果 |
| is_last | boolean | 是否为最终结果 |
| auth_id | string | 用户唯一 ID |
| result_id | int | 结果序号 |
| text | string | 识别文本内容 |
声纹结果：
注意： 需要传入参数
group_id、feature_id时生效
{
"code": "0",
"data": {
"sub": "vpr",
"vpr_feature_id": "xxx"
},
"action": "result",
"desc": "success",
"sid": "05f6a28a-718e-40dc-9f68-d62cf3c02271"
}
VAD前端点结果：
用户开始说话时下发前端点结果
注意：
vad_type为evad时才会下发前端点结果frame_properties.frame_size和frame_properties.frame_ms参数正确配置时，vad前端点结果会包含data.bos_ms字段，代表vad前端点时间
{
"code": "0",
"data": {
"sub": "vad",
"result_id": 0,
"info": "start",
"bos_ms": 500 //frame_properties正确配置时返回
},
"action": "result",
"desc": "success",
"sid": "7a0dff95-9f95-4a68-921e-8ceb72c33281"
}
VAD后端点结果：
用户说话结束时下发后端点结果
注意：
- VAD 结果可能会在最终识别结果前下发
frame_properties.frame_size和frame_properties.frame_ms参数正确配置时，va后端点结果会包含data.eos_ms字段，代表vad后端点时间
{
"code": "0",
"data": {
"sub": "vad",
"result_id": 0,
"info": "end"
"eos_ms": 2500 //frame_properties正确配置时返回
},
"action": "result",
"desc": "success",
"sid": "7a0dff95-9f95-4a68-921e-8ceb72c33281"
}
当会话所有结果均已下发后，服务端会下发一个结束指令消息，表示该会话已经结束。
结束消息：
{
"code": "0",
"data": "",
"action": "finish",
"desc": "success",
"sid": "05f6a28a-718e-40dc-9f68-d62cf3c02271"
}
云端在会话结束后会下发结束信息，并断开连接。
| 错误码 | 错误信息 | 说明 |
|---|---|---|
| 0 | 成功 | 请求成功 |
| 401 | 鉴权失败 | Token 无效或过期 |
| 400 | 设备在其他地方上线 | 同一设备在其他地方建立了连接 |
| 500 | 链路异常 | 包括调度异常关闭等 |
| 10114 | 参数错误 | 请求参数格式或内容不正确 |
| 11101 | 其他错误 | 其他未分类的错误，查看 desc 字段 |
单次识别的完整交互流程如下：
connected 响应start，fullduplex: "0" 或不设置）→ 收到 started 响应result 消息，sub: "iat"）end）或等待自动结束finish）在连续对话模式下（设置 fullduplex: "1"），可以在同一个会话中多次进行语音识别，无需每次创建新会话。完整流程如下：
初始化阶段：
connected 响应start，设置 fullduplex: "1"）→ 收到 started 响应result 消息，sub: "iat"）result 消息，sub: "iat"）end）或等待连接超时finish）