# WebSocket 接口文档

# 简介

本文主要描述基于 WebSocket 协议之上的实时 AIUI 交互接口协议,基于该接口协议客户端可以由 Java、 C#、 C++、 JavaScript、Go 等开发语言实现。

# 示例代码

websocket (opens new window)

# 接口说明

实时 AIUI 服务是基于 WebSocket 协议实现数据的传输的。主要包括三个阶段:连接的建立实时通信阶段连接的断开

注意:

本接口是基于会话的短连接接口,用户每次交互前需要新建连接,会话完成后,讯飞侧断开连接。单次会话过程中支持流式交互,即客户端不断上传音频等数据,讯飞侧不断下发服务结果。

交互时序图:

  1. 设备端具备端点检测功能,交互时序图如下:

  1. 设备端不具备端点检测功能,需依赖云端端点检测功能,交互时序图如下:

# 连接的建立

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&param=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"
}

# 连接的断开

会话正常结束或异常结束时,连接的断开都是由讯飞侧发起,客户端不应主动断开连接; 连接断开有以下情况:

  1. 会话正常结束,讯飞侧会在 is_finish = true 的结果下发完成后,断开连接;
  2. 会话报错,讯飞侧会在下发错信息(action="error"且code不为"0")完成后,断开连接;
  3. 会话超时,在连接总时长超过 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 并发数超过限制 申请提高并发授权或关闭部分连接