本接口是基于 WebSocket 协议实现数据的传输的。接口提供两个版本:
gateway:
ws[s]://api.listenai.com/v1/interaction
dispatch:
ws[s]://api.listenai.com/v1/dispatch
Authorization: Bearer {token}
请查阅端侧授权接入
文档。
请求参数格式:需要urlencode
key1=value1&key2=value2
请求示例:
ws[s]://api.listenai.com/v1/interaction?param=xxxx
请求参数说明:
参数 | 类型 | 必须 | 说明 | 示例 |
---|---|---|---|---|
param | string | 是 | 相关参数 JSON 串经Base64 编码后的字符串,详见 param 字段说明 | eyJzY2VuZSI6Im1haW4ifQ== |
param参数说明:
参数 | 类型 | 必须 | 说明 | 示例 |
---|---|---|---|---|
auth_id | string | 是 | 用户唯一ID(32位字符串,包括英文小写字母与数字,开发者需保证该值与终端用户一一对应) | 4d0c4412769b62f0f44134ce9f2db11f |
llm_app | string | 否 | 由客户端指定的大模型应用id | 9ebe7088 |
成功:
{
"action":"connected",
"cid":"cidf415ba9c@dx8d0d18b0d6dd3eef00",
"code":"0",
"data":"",
"desc":"success"
}
失败:
{
"action":"error",
"cid":"cidf415ba9c@dx8d0d18b0d6dd3eef00",
"code":"11101",
"data":"",
"desc":"error desc"
}
Websocket 连接建立之后,进入实时通信阶段,可以进行会话的创建、数据的上传、结果的接收等
操作,整体的交互协议分为指令和数据,分别对应TEXT消息和BINARY消息。
连接建立之后,就可以开始创建会话,创建会话是为了在长连接中标识一次会话请求的起点,创建
会话之后,在会话结束之前,所有请求的数据和指令均属于该会话。
请求示例:
{
"action":"start",
"params":{
"data_type":"audio",
"aue":"raw",
"features":[
"nlu",
"tts"
],
"asr_properties":{
"ent":"home-va"
},
"tts_properties":{
"vcn":"x4_yezi"
},
"nlu_properties":{
"sn":"xxxxxxxx"
}
}
}
参数说明
参数 | 类型 | 必须 | 说明 | 示例 |
---|---|---|---|---|
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, 单声道 speex: speex格式 speed-wb: speex-wb格式 ico: ico格式 |
raw |
params.speex_size | int | 否 | 音频数据格式为speex、speex-web时必填 | 70 |
params.fullduplex | string | 否 | 是否开启全双工模式,开启传"1" | "1" |
features | array | 否 | 自定义nlp功能,默认为["nlu"、"tts"]: nlu: 语义理解与回复(aiui或llm) tts: 下发tts音频链接 不需要使用nlp功能是,传空数组 |
["nlu", "tts"] |
params.asr_properties | object | 否 | 端上指定的asr参数 | |
params.tts_properties | object | 否 | 端上指定的tts参数 | |
params.nlu_properties | object | 否 | 端上指定的nlu参数 |
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后端点 | 400 |
ent | string | 否 | 识别引擎 | sms-aiui16k |
pd | string | 否 | ||
svad | int | 否 |
tts_properties
参数 | 类型 | 必须 | 说明 | 示例 |
---|---|---|---|---|
tts_appid | string | 否 | 自定义appid | |
tts_apikey | string | 否 | 自定义apikey | |
tts_apisecret | string | 否 | 自定义apisecret | |
vcn | string | 否 | 发音人 | "x_dangdang" |
ent | string | 否 | 引擎 | "xtts" |
volume | string | 否 | 音量:1-100 | "50" |
speed | string | 否 | 语速:1-100 | "50" |
pitch | string | 否 | 声调:1-100 | "50" |
nlu_properties
参数 | 类型 | 必须 | 说明 | 示例 |
---|---|---|---|---|
aiui_appid | string | 否 | 自定义appid | |
aiui_apikey | string | 否 | 自定义apikey | |
nlp_mode | string | 否 | nlp类型: aiui llm |
"aiui" |
scene | string | 否 | 自定义scene,默认main | "main" |
sn | string | 否 | 设备sn | "xxxxxx" |
lat | string | 否 | 纬度 | |
lng | string | 否 | 经度 | |
auth_id | string | 否 | ||
clean_dialog_history | string | 否 | "user" | |
abilities | object | 否 | 设备支持的能力列表 | - |
abilities示例
// 设备支持闹钟能力,创建和删除
{
"params":{
"nlu_properties":{
"abilities": [
{
"name": "alarm",
"intents": ["create", "delete"]
},
// ...
]
}
}
}
在交互过程中,客户端不断构造 binary message 发送到服务端,内容是音频或文本的二进制数
据。一个会话中,二进制文本数据只需要发送一次。
客户端可以主动结束音频发送,云端会结束识别并进行对应的处理。指令内容如下:
{
"action": "end"
}
会话创建成功
{
"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"
}
vad结果(注:vad结果可能会在最终识别结果前下发)
{
"code":"0",
"data":{
"sub":"vad",
"result_id":0,
"info":"end"
},
"action":"result",
"desc":"success",
"sid":"7a0dff95-9f95-4a68-921e-8ceb72c33281"
}
语义结果
{
"code":"0",
"data":{
"sub":"nlp",
"auth_id":"4d0c4412769b62f0f44134ce9f2db11f",
"result_id":1,
"intent":{
"semantic":[
{
"slots":[
{
"name":"location.city",
"value":"广州市",
"normValue":"广州市"
},
{
"name":"location.cityAddr",
"value":"广州",
"normValue":"广州"
},
{
"name":"location.type",
"value":"LOC_BASIC",
"normValue":"LOC_BASIC"
},
{
"name":"queryType",
"value":"确认"
},
{
"name":"questionWord",
"value":"需要"
},
{
"name":"subfocus",
"value":"伞"
},
{
"name":"datetime",
"value":"今天",
"normValue":"{\"datetime\":\"2023-11-16\",\"suggestDatetime\":\"2023-11-16\"}"
}
],
"intent":"QUERY"
}
],
"shouldEndSession":"true",
"dialog_stat":"DataValid",
"data":{
"result":[
]
},
"save_history":true,
"uuid":"ara3d116b3a@dx000118b0e1c0a10b00",
"version":"171.0",
"sid":"ara3d116b3a@dx000118b0e1c0a10b00",
"rc":0,
"answer":{
"text":"不用带伞,今天广州阴",
"type":"T"
},
"used_state":{
"state_key":"fg::weather::default::default",
"state":"default"
},
"service":"weather",
"state":{
"fg::weather::default::default":{
"state":"default"
}
},
"text":"今天广州的天气怎么样?需要带伞吗?",
"category":"IFLYTEK.weather"
}
},
"action":"result",
"desc":"success",
"sid":"ebd611e1-f4ec-4d3c-be4d-ed8c122ea96d"
}
tts结果
{
"code":"0",
"data":{
"sub":"tts",
"is_last":true,
"auth_id":"3fdc7e97c0d351991975662bd425e999",
"result_id":0,
"content":"aHR0cDovL2ludGVncmF0aW9uLXR0cy5pZmx5b3MuY24vbGl2ZS9kNjVkYzUyNDJhNGRhMGY4NWFjZDZhMTY3YmM0OWMyOWNlOTdkNGI1Lm1wMw=="
},
"action":"result",
"desc":"success",
"sid":"9470b468-ab3b-44de-ba95-24ab9dc60770"
}
在会话所以结果均已下发,则会下发一个结束指令消息,表示该会话已经结束。
{
"code":"0",
"data":"",
"action":"finish",
"desc":"success",
"sid":"05f6a28a-718e-40dc-9f68-d62cf3c02271"
}
设备只使用asr,需要将nlp处理功能关闭,params.features
字段传空数组,如:
{
"action":"start",
"params":{
"data_type":"audio",
"aue":"raw",
"features":[],
"asr_properties":{
"ent":"sms-haier-test"
}
}
}
设备只使用nlp相关功能,不使用asr,需要将params.data_type
设置成text
,上传binary数据阶段上传文本的二进制数据,如:
{
"action":"start",
"params":{
"data_type":"text",
"features":["nlu", "tts"],
"tts_properties":{
"vcn":"x_dangdang"
},
"nlu_properties":{
"sn":"xxxxxxxx"
}
}
}
支持设备端上传文本合成对应的tts音频,返回tts音频连接,需要将params.data_type
设置成text
,同时params.features
字段只填tts
,如:
{
"action":"start",
"params":{
"data_type":"text",
"features":["tts"],
"tts_properties":{
"vcn":"x_dangdang"
}
}
}
错误码 | 错误信息 |
---|---|
401 | 鉴权失败 |
10114 | 参数错误 |
400 | 设备在其他地方上线 |
500 | 链路异常(包括调度异常关闭) |