# WebSocket 接口文档
# 简介
本文主要描述基于 WebSocket 协议之上的实时 AIUI 交互接口协议，基于该接口协议客户端可以由 Java、 C#、 C++、 JavaScript、Go 等开发语言实现。
# 示例代码
# 接口说明
实时 AIUI 服务是基于 WebSocket 协议实现数据的传输的。主要包括三个阶段：连接的建立和实时通信阶段和连接的断开。
注意：
本接口是基于会话的短连接接口，用户每次交互前需要新建连接，会话完成后，讯飞侧断开连接。单次会话过程中支持流式交互，即客户端不断上传音频等数据，讯飞侧不断下发服务结果。
交互时序图：
- 设备端具备端点检测功能，交互时序图如下：
- 设备端不具备端点检测功能，需依赖云端端点检测功能，交互时序图如下：
# 连接的建立
WebSocket 握手阶段主要用于业务参数声明和权限校验，参数在握手请求的 url 中指定，握手请求和参数必须符合 websocket 协议规范（rfc6455）。握手成功后，服务端会保持连接 120s，超过 120s 讯飞主动断开连接。同时，讯飞侧有连接的保活监测，连续 30s 无数据交互，讯飞主动断开连接。
# 请求地址
ws[s]://wsapi.xfyun.cn/v1/aiui
# 请求参数
请求参数格式： 需 url encode
key1=value1&key2=value2…
请求示例：
ws[s]://wsapi.xfyun.cn/v1/aiui?appid=xxx&checksum=xxx&curtime=xxx¶m=xxx
请求参数详细说明：
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| appid | string | 是 | AIUI开放平台注册申请应用的应用ID(appid) | 594b62c3 |
| curtime | string | 是 | 当前UTC时间戳，从1970年1月1日0点0 分0 秒开始到现在的秒数 | 1502607694 |
| signtype | string | 否 | 签名算法，可选值：md5，sha256，默认为 md5 | |
| checksum | string | 是 | 令牌，计算方法：(apikey + curtime + param)，三个值拼接的字符串，根据signtype指定的加密算法加密，其中apikey可在AIUI开放平台设置。 | 02607694eyjzy2vuzsi6im1haw4ifq |
| param | string | 是 | 相关参数 JSON 串经 Base64 编码后的字符串，详见 param 字段说明 | eyJzY2VuZSI6Im1haW4ifQ== |
注：
- apikey：接口密钥，用户可在 AIUI 开放平台管理；
- checksum 有效期：出于安全性考虑，每个 checksum 的有效期为 5 分钟(用 curtime 计算)，同时 curtime 要与标准时间同步，否则，时间相差太大，服务端会直接认为 curtime 无效；
- BASE64 编码采用 MIME 格式，字符包括大小写字母各26个，加上10个数字，和加号 + ，斜杠 / ，一共64个字符。
- BASE64 编码后大小会增加约1/3
*checksum *生成示例（如加密算法为 md5）：
String apikey="abcd1234";
String curtime="1502607694";
String param="eyAiYXVmIjogImF1ZGlvL0wxNjtyYXR...";
String checksum=MD5(apikey+curtime+param);
param 字段详细说明：
param 为相关参数 JSON 串经 Base64 编码后的字符串，原始json字段说明如下：
通用配置参数：
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| scene | string | 是 | 情景模式 | main |
| auth_id | string | 是 | 用户唯一ID（32位字符串，包括英文小写字母与数字，开发者需保证该值与终端用户一一对应） | 2049a1b2fdedae553bd03ce6f4820ac4 |
| data_type | string | 是 | 数据类型，可选值：text（文本），audio（音频） | text |
| interact_mode | string | 否 | 交互模式，可选值：continuous（持续交互），oneshot（一次性交互），默认为 continuous，注意，持续交互会返回多个识别和语义结果 | continuous |
语义相关参数：
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| lat | string | 否 | 纬度 | 31.83 |
| lng | string | 否 | 经度 | 117.14 |
| topn | string | 否 | 多候选词 | 2 |
| pers_param | string | 否 | 个性化参数，json字符串，目前支持用户级（auth_id）、应用级（appid）和用户自定义级，不支持透传其他参数。 | "{\"auth_id\":\"xxxxxx\"}" |
| clean_dialog_history | string | 否 | 清除交互历史：user（手动清除），auto（系统默认），默认为auto | user |
识别相关参数：
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| aue | string | 否 | 音频编码，可选值：raw（未压缩的pcm或wav格式）、speex（speex格式，sample_rate=8000）、speex-wb（宽频speex格式，sample_rate=16000），默认为 raw | raw |
| sample_rate | string | 否 | 音频采样率，可选值：16000（16k采样率）、8000（8k采样率），默认为16000 | 16000 |
| speex_size | string | 否 | speex音频帧大小，speex音频必传。详见speex_size与speex库压缩等级关系表 | 60 |
| result_level | string | 否 | 结果级别，可选值：plain（精简），complete（完整），默认 plain | plain |
| vad_info | string | 否 | 是否需要云端返回 vad 信息，可选值：end（末端点） | end |
| cloud_vad_eos | string | 否 | 后端点静音时长，单位ms | 700 |
所见即可说参数：
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| iat_user_data | string | 内部 | 所见即可说-识别 | |
| nlp_user_data | string | 内部 | 所见即可说-语义 |
iat_user_data示例：
{
"recHotWords":"播报内容|地图显示|路线优先",//会话级热词
"sceneInfo":{}
}
nlp_user_data示例：
{
"res":[{
"res_name":"vendor_applist",//资源名称
"data":"xxxxx"//数据的base64编码
}],
"skill_name":"telephone"//对应的技能名称
}
单合成相关参数（单合成scene=IFLYTEK.tts）：
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| ent | string | 内部 | 引擎类型，默认为xtts | xtts |
| vcn | string | 内部 | 发音人，不同的发音人代表了不同的音色，如男声、女声、童声等，默认为x_xiaoyan。详细请参照《发音人列表》 | x_xiaoyan |
| speed | string | 内部 | 语速，合成音频对应的语速，取值范围：[0,100]，数值越大语速越快。默认值：50 | 50 |
| volume | string | 内部 | 音量，合成音频的音量，取值范围：[0,100]，数值越大音量越大。默认值：50 | 50 |
| pitch | string | 内部 | 语调，合成音频的音调，取值范围：[0,100]，数值越大音调越高。默认值：50 | 50 |
speex_size与speex库压缩等级（quantity）关系表：
| quantity（压缩等级） | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| speex | 6 | 10 | 15 | 20 | 20 | 28 | 28 | 38 | 38 | 46 | 62 |
| speex-wb | 10 | 15 | 20 | 25 | 32 | 42 | 52 | 60 | 70 | 86 | 106 |
X-Param生成示例：
原始JSON串：
{
"scene":"main",
"aue":"raw",
"sample_rate":"16000",
"pers_param":"{\"auth_id\":\"xxxxxx\"}",
"data_type":"audio",
"auth_id":"2049a1b2fdedae553bd03ce6f4820ac4"
}
BASE64编码（即X-Param）：
eyJzY2VuZSI6Im1haW4iLCJhdWUiOiJyYXciLCJzYW1wbGVfcmF0ZSI6IjE2MDAwIiwicGVyc19wYXJhbSI6IntcImF1dGhfaWRcIjpcInh4eHh4eFwifSIsImRhdGFfdHlwZSI6ImF1ZGlvIiwiYXV0aF9pZCI6IjIwNDlhMWIyZmRlZGFlNTUzYmQwM2NlNmY0ODIwYWM0In0=
注：
- vad 信息与开发者设置的尾静音时长（cloud_vad_eos）有关，默认为 30s，开发者可通过 cloud_vad_eos 参数进行设置。云端对音频进行vad检测，发现静音时长超过该值时会返回vad信息。建议该值大于 400 ms。
param生成示例：
原始JSON串：
{
"scene":"main",
"aue":"raw",
"sample_rate":"16000",
"data_type":"audio",
"auth_id":"2049a1b2fdedae553bd03ce6f4820ac4"
}
BASE64编码（即 param）：
eyJzY2VuZSI6Im1haW4iLCJhdWUiOiJyYXciLCJzYW1wbGVfcmF0ZSI6IjE2MDAwIiwiZGF0YV90eXBlIjoiYXVkaW8iLCJhdXRoX2lkIjoiMjA0OWExYjJmZGVkYWU1NTNiZDAzY2U2ZjQ4MjBhYzQifQ==
# 返回信息
成功：
{
"action":"started",
"code":"0",
"data":"",
"desc":"success",
"sid":"awa00000001@ch27f00e2d00fe430100"
}
失败：
{
"action":"error",
"code":"10114",
"data":"",
"desc":"time out|illegal curtime",
"sid":"awa00000049@ch78170e55bcd92a0100"
}
# 实时通信阶段
Websocket 连接建立之后，进入实时通信阶段，此时客户端的主动操作有两种：上传数据和上传结束符，被动操作有两种：接收结果和错误信息
# 上传数据
在交互过程中，客户端不断构造 binary message 发送到服务端，内容是音频或文本的二进制数据。注意，分片上传时，总分片数需小于 3000，且 speex 音频每次发送的字节数应为 speex_size 的整数倍。
# 上传结束符
在音频或文本数据上传完成后，客户端需构造一个特殊的 binary message 发送到服务端，作为发送数据结束标志，内容是字符串 "--end--" 的二进制数据。 音频最大长度不超过 60s，大小不超过 2 MB，文本最长长度不超过 1000 字节。
# 接收结果
在交互过程中，服务端不断返回 text message 到客户端，包含识别、语义、后处理、vad检测等结果。当所有结果发送完毕后，服务端断开连接，交互结束。
识别结果（完整）：
{
"action":"result",
"code":"0",
"data":{
"sub":"iat",
"auth_id":"xxx",
"text":{
"sn":1,
"ls":false,
"bg":0,
"ed":0,
"ws":[
{
"bg":0,
"cw":[
{
"sc":0,
"w":"今天"
}
]
},
{
"bg":0,
"cw":[{
"sc":0,
"w":"星期"
}
]
},
{
"bg":0,
"cw":[{
"sc":0,
"w":"几"
}
]
}
]
},
"json_args":{
"language":"zh-cn",
"accent":"mandarin"
},
"result_id":1,
"is_last":true,
"is_finish":true
},
"desc":"success",
"sid":"awa00000001@ch27f00e2d00fe430100"
}
识别结果（精简）：
{
"action":"result",
"code":"0",
"data":{
"sub":"iat",
"auth_id":"xxx",
"text":"今天星期几",
"json_args":{
"language":"zh-cn",
"accent":"mandarin"
},
"result_id":1,
"is_last":true,
"is_finish":true
},
"desc":"success",
"sid":"awa00000001@ch27f00e2d00fe430100"
}
语义结果：
{
"action":"result",
"code":"0",
"data":{
"sub":"nlp",
"auth_id":"xxx",
"intent":{
"answer":{
"text":"今天是2018年03月20日 戊戌年二月初四 星期二",
"type":"T"
},
"match_info":{
"type":"gparser_path",
"value":"-----"
},
"operation":"ANSWER",
"rc":0,
"service":"datetime",
"sid":"ara00000002@ch5aa00e0ba5e72a0100",
"state":{
},
"text":"今天星期几",
"uuid":"atn004a008d@ch1aa50e0ba5e96f1d01"
},
"result_id":1,
"is_last":true,
"is_finish":true
},
"desc":"success",
"sid":"awa00000001@ch03040e2d0ad3430100"
}
tpp 结果：
{
"action":"result",
"code":"0",
"data":{
"sub":"tpp",
"auth_id":"xxx",
"content":"xxx",
"result_id":1,
"is_last":true,
"is_finish":true
},
"desc":"success",
"sid":"awa00000001@ch03040e2d0ad3430100"
}
合成结果：
{
"action":"result",
"code":"0",
"data":{
"sub":"tts",
"auth_id":"xxx",
"content":"YXNkZmFzZGZhc2RmYWRmYWRmYWZkc2FmZGFzZGZhc2Q.....",
"result_id":0,
"json_args":{
"cancel":"0",
"dte":"raw",
"dts":1,
"frame_id":59,
"text_end":220,
"text_percent":11
},
"is_last":true,
"is_finish":true
},
"desc":"success",
"sid":"awa00000001@ch03040e2d0ad3430100"
}
# 接收错误信息
在交互过程中，在服务端出现异常而中断服务时（如会话超时），会将异常信息以 text message 形式返回给客户端并关闭连接。
{
"action":"error",
"code":"10205",
"data":"",
"desc":"websocket read error|read dispatch data error: i/o timeout",
"sid":"awa00000003@ch78b90e18f1d4630100"
}
# 接收vad信息
若用户设置需要需要云端返回 vad 信息，则在交互过程中，会将 vad 信息以 text message 形式返回给客户端。
{
"action":"vad",
"code":"0",
"data":{
"vad_info":"end"
},
"desc":"success",
"sid":"awa00000001@ch2ba00e4f8e8c430100"
}
# 连接的断开
会话正常结束或异常结束时，连接的断开都是由讯飞侧发起，客户端不应主动断开连接； 连接断开有以下情况：
- 会话正常结束，讯飞侧会在 is_finish = true 的结果下发完成后，断开连接；
- 会话报错，讯飞侧会在下发错信息（action="error"且code不为"0")完成后，断开连接；
- 会话超时，在连接总时长超过 2min 或连续 30s 无数据交互时，讯飞侧会断开连接。
无论上传的数据是否有效，客户端都不应主动断开连接。如果客户要中断数据上传，必须通过发送 end 指令(--end--)实现，此时讯飞会在下发完相应结果后断开连接。
# 结果说明
返回字段说明如下：
| 参数 | 类型 | 说明 |
|---|---|---|
| action | string | 操作类型（started-握手，result-结果，error-出错，vad-端点检测） |
| code | string | 返回码，详见错误码 |
| data | object | 结果数据 |
| desc | string | 描述 |
| sid | string | 会话id，调试时提供给讯飞帮助定位问题 |
data字段说明如下：
| 参数 | 类型 | 说明 |
|---|---|---|
| sub | string | 业务类型（nlp-语义，iat-识别，tpp-后处理，itrans-翻译，tts-合成） |
| intent | object | 语义结果数据 |
| text | object/string | 识别结果，object-分词结果，string-精简结果 |
| content | object | 后处理、翻译、合成等结果 |
| auth_id | string | 用户ID回传 |
| is_last | bool | 是否为该业务的最后一条结果（如识别的最后一条结果，语义的最后一条结果） |
| is_finish | bool | 是否为本次会话的最后一条结果 |
| result_id | int | 结果序号 |
| json_args | object | 结果参数 |
intent与text字段详见AIUI开放平台说明
语义后合成json_args字段说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| dte | string | 合成数据编码，如raw等 |
| dts | int | 数据状态 |
| frame_id | int | 合成语音的流编号，1代表合成音频的第一个返回结果 |
| text_percent | int | 当前合成音频的进度百分比 |
| error | string | 错误信息 |
| cancel | string | 是否已取消 |
| text_end | int | 当前合成音频对应文本的结束位置（按照UTF16编码计算） |
# 错误码
| 错误码 | 描述 | 说明 | 处理方式 |
|---|---|---|---|
| 0 | success | 成功 | |
| 10105 | illegal access | 没有权限 | 检查apikey，ip，checksum等授权参数是否正确 |
| 10106 | invalid parameter | 无效参数或参数值为空 | 上传必要的参数， 检查参数格式以及编码 |
| 10107 | illegal parameter | 非法参数值 | 检查参数值是否超过范围或不符合要求 |
| 10109 | invalid data | 无效数据 | 检查上传数据长度是否超过限制 |
| 10110 | no license | 无授权许可 | 提供请求的 appid、 auth_id 向服务商反馈 |
| 10114 | time out | 超时 | 检测网络连接或联系服务商 |
| 10700 | engine error | 引擎错误 | 提供接口返回值，向服务商反馈 |
| 11004 | server up error | 服务请求上线错误 | 提供接口返回值，向服务商反馈 |
| 10202 | websocket connect error | 套接字连接异常 | 提供接口返回值，向服务商反馈 |
| 10204 | websocket write error | 网络数据包发送异常 | 提供接口返回值，向服务商反馈 |
| 10205 | websocket read error | 网络数据包接收异常 | 提供接口返回值，向服务商反馈 |
| 10301 | parse data error | 解析消息体失败 | 提供接口返回值，向服务商反馈 |
| 11201 | quantity not enough | 并发数超过限制 | 申请提高并发授权或关闭部分连接 |