# 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 | 并发数超过限制 | 申请提高并发授权或关闭部分连接 |