# 接口说明
AIUI是科大讯飞提供的一套人机智能交互解决方案, 旨在实现人机交互无障碍,使人与机器之间可以通过语音、图像、手势等自然交互方式,进行持续,双向,自然地沟通。
# 示例代码
# 接口地址
POST https://openapi.xfyun.cn/v2/aiui HTTP/1.1
# API说明
- 授权认证,调用接口需要将 Appid,CurTime, Param 和 CheckSum 信息放在 HTTP 请求头中;
- 接口统一为 UTF-8 编码;
- 接口支持 http 和 https;
- 请求方式为POST。
# 授权认证
在调用接口时,需要在 Http Request Header 中配置以下参数用于授权认证:
参数 | 格式 | 说明 | 必须 |
---|---|---|---|
X-Appid | string | 讯飞AIUI开放平台注册申请应用的应用ID(appid) | 是 |
X-CurTime | string | 当前UTC时间戳,从1970年1月1日0点0 分0 秒开始到现在的秒数 | 是 |
X-Param | string | 相关参数JSON串经Base64编码后的字符串,见各接口详细说明 | 是 |
X-CheckSum | string | 令牌,计算方法:MD5(apiKey + curTime + param),三个值拼接的字符串,进行MD5哈希计算(32位小写),其中apiKey由讯飞提供,调用方管理。 | 是 |
注:
- apiKey:接口密钥,由讯飞AIUI开放平台提供,调用方管理;
- checkSum 有效期:出于安全性考虑,每个 checkSum 的有效期为 5 分钟(用 curTime 计算),同时 curTime 要与标准时间同步,否则,时间相差太大,服务端会直接认为 curTime 无效;
- BASE64 编码采用 MIME 格式,字符包括大小写字母各26个,加上10个数字,和加号 + ,斜杠 / ,一共64个字符。
*checkSum *生成示例:
String apiKey="abcd1234";
String curTime="1502607694";
String param="eyAiYXVmIjogImF1ZGlvL0wxNjtyYXR...";
String checkSum=MD5(apiKey+curTime+param);
# IP白名单
在调用所有业务接口时,授权认证通过后,检查调用方 ip 是否在讯飞开放平台配置的 ip 白名单中。存在通过,否则拒绝提供服务。注意,应用创建后需及时进行 ip 白名单的设置,否则调用接口时会因应用信息不完整而报错。
拒绝提供服务的返回值:
{
"code":"10105",
"desc":"illegal access|illegal client_ip",
"data":[],
"sid":"xxxxxx"
}
# 请求参数
在 Http Request Header 中配置授权认证参数,见【授权认证】。 其中 X-Param 为各配置参数组成的 JSON 串经 BASE64 编码之后的字符串,原始 JSON 串各字段说明如下:
JSON字段 | 类型 | 必须 | 说明 | 示例 |
---|---|---|---|---|
scene | string | 是 | 情景模式(目前不支持 wpgs-识别动态修正 场景) | main |
auth_id | string | 是 | 用户唯一ID(32位字符串,包括英文小写字母与数字,开发者需保证该值与终端用户一一对应) | 2049a1b2fdedae553bd03ce6f4820ac4 |
data_type | string | 是 | 数据类型,可选值:text(文本),audio(音频) | text |
sample_rate | string | 否 | 音频采样率,可选值:16000(16k采样率)、8000(8k采样率),默认为16000 | 16000 |
aue | string | 否 | 音频编码,可选值:raw(未压缩的pcm或wav格式)、speex(speex格式,即sample_rate=8000的speex音频)、speex-wb(宽频speex格式,即sample_rate=16000的speex音频),默认为 raw | raw |
speex_size | string | 否 | speex音频帧大小,speex音频必传。详见speex_size与speex库压缩等级关系表 | 60 |
lat | string | 否 | 纬度 | 31.83 |
lng | string | 否 | 经度 | 117.14 |
pers_param | string | 否 | 个性化参数,json字符串,目前支持用户级(auth_id)、应用级(appid)和用户自定义级,不支持透传其他参数。 | "{"auth_id":"xxxxxx"}" |
result_level | string | 否 | 结果级别,可选值:plain(精简),complete(完整),默认 plain | plain |
interact_mode | string | 否 | 是否开启云端vad,可选值:continuous(开启),oneshot(关闭),默认为 continuous,注意,开启后可能返回多个识别和语义结果 | continuous |
topn | string | 否 | 多候选词 | 2 |
client_ip | string | 否 | 设备终端IP,可用于定位,定位优先级:文本中地理位置>经纬度信息>设备终端IP | 61.191.24.236 |
clean_dialog_history | string | 否 | 是否清除交互历史,可选值:auto(不清除)、user(清除),默认为不清除 | user |
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\":\"2049a1b2fdedae553bd03ce6f4820ac4\"}",
"data_type":"audio",
"auth_id":"2049a1b2fdedae553bd03ce6f4820ac4"
}
BASE64编码(即X-Param):
eyJzY2VuZSI6Im1haW4iLCJhdWUiOiJyYXciLCJzYW1wbGVfcmF0ZSI6IjE2MDAwIiwicGVyc19wYXJhbSI6IntcImF1dGhfaWRcIjpcIjIwNDlhMWIyZmRlZGFlNTUzYmQwM2NlNmY0ODIwYWM0XCJ9IiwiZGF0YV90eXBlIjoiYXVkaW8iLCJhdXRoX2lkIjoiMjA0OWExYjJmZGVkYWU1NTNiZDAzY2U2ZjQ4MjBhYzQifQ==
在 Http Request Body 中配置以下参数:
将音频/文本的二进制字节数组放入请求body中,数据长度限制为:音频文件大小 < 2MB, 时长 < 60s (其中 speex 音频大小 < 512KB), 文本长度 < 2000B
# 返回值
返回结果为 JSON 字符串,各字段说明如下:
JSON字段 | 类型 | 说明 |
---|---|---|
code | string | 结果码(具体见错误码) |
data | array | 结果数据 |
desc | string | 描述 |
sid | string | 会话ID |
其中 sid 字段主要用于追查问题,如果出现问题,可以提供 sid 给讯飞技术人员帮助确认问题。
data 字段说明如下:
JSON字段 | 类型 | 说明 |
---|---|---|
sub | string | 业务类型:iat(识别),nlp(语义),tpp(后处理),itrans(翻译) |
text | object/string | 识别结果:详细结果(object),精简结果(string) |
intent | object | 语义结果 |
content | object/string | 后处理 (string),翻译 (object)等结果 |
result_id | number | 结果序号,同一业务逐渐递增 |
text 详细结果字段说明:
JSON字段 | 英文全称 | 类型 | 说明 |
---|---|---|---|
sn | sentence | number | 第几句 |
ls | last sentence | boolean | 是否最后一句 |
bg | begin | number | 开始 |
ed | end | number | 结束 |
ws | words | array | 词 |
cw | chinese word | array | 中文分词 |
w | word | string | 单字 |
sc | score | number | 分数 |
intent 字段说明:
详见 AIUI开放平台语义协议
content 字段说明:
若业务类型为 tpp (后处理),则为后处理接口返回的内容;若业务类型为 itrans (翻译),则为翻译结果 JSON 对象,其字段说明如下:
JSON字段 | 类型 | 说明 |
---|---|---|
from | string | 源语言语种 |
to | string | 目标语言语种 |
result | string | 翻译的结果 |
src | string | 源语言结果 |
dst | string | 翻译的目标语言结果 |
sid | string | 翻译引擎sid |
ret | number | 调用结果 |
接口调用返回值示例: 失败:
{
"code":"10105",
"data":[],
"desc":"illegal access|illegal X-CheckSum",
"sid":"ara00000013@cha5f90e07ef6d2a0100"
}
成功:
{
"code":"0",
"data":[
{
"sub":"iat",
"auth_id":"2049a1b2fdedae553bd03ce6f4820ac4",
"text":"今天星期几",
"result_id":1
},
{
"sub":"iat",
"auth_id":"2049a1b2fdedae553bd03ce6f4820ac4",
"text":"明天北京的天气怎么样",
"result_id":2
},
{
"sub":"nlp",
"auth_id":"2049a1b2fdedae553bd03ce6f4820ac4",
"intent":{
"answer":{
"text":"今天是星期五"
},
"dialog_stat":"dataInvalid",
"rc":0,
"save_history":true,
"semantic":[
{
"intent":"WHATWEEK",
"slots":[
{
"name":"datetime",
"normValue":"{"datetime":"2018-08-10","suggestDatetime":"2018-08-10"}",
"value":"今天"
}
]
}
],
"service":"datetimeX",
"sid":"atn005b5015@dx00070ec890d8a11001",
"state":{
"fg::datetimeX::default::default":{
"state":"default"
}
},
"text":"今天星期几",
"used_state":{
"state":"default",
"state_key":"fg::datetimeX::default::default"
},
"uuid":"atn005b5015@dx00070ec890d8a11001"
},
"result_id":1
},
{
"sub":"nlp",
"auth_id":"2049a1b2fdedae553bd03ce6f4820ac4",
"intent":{
"answer":{
"text":"北京明天全天雷阵雨转中雨,出门记得带伞,气温24℃ ~ 30℃,有东风微风,有点热,适合穿短袖短裙等夏季清凉衣物。"
},
"data":{
"result":[
{
"airData":124,
"airQuality":"轻微污染",
"city":"北京",
"date":"2018-08-10",
"dateLong":1533830400,
"date_for_voice":"今天",
"exp":{
"cl":{
"expName":"晨练指数",
"level":"适宜",
"prompt":"天气不错,空气清新,是您晨练的大好时机,建议不同年龄段的人们积极参加户外健身活动。"
},
"co":{
"expName":"舒适度指数",
"level":"较不舒适",
"prompt":"白天天气多云,同时会感到有些热,不很舒适。"
},
"ct":{
"expName":"穿衣指数",
"level":"炎热",
"prompt":"天气炎热,建议着短衫、短裙、短裤、薄型T恤衫等清凉夏季服装。"
},
"dy":{
"expName":"钓鱼指数",
"level":"不宜",
"prompt":"天气太热,不适合垂钓。"
},
"fs":{
"expName":"防晒指数",
"level":"中等",
"prompt":"属中等强度紫外辐射天气,外出时应注意防护,建议涂擦SPF指数高于15,PA+的防晒护肤品。"
},
"gj":{
"expName":"逛街指数",
"level":"较适宜",
"prompt":"天气较好,虽然天气较热,还是较适宜逛街的,穿上透气的衣服就可放心出门了。"
},
"gm":{
"expName":"感冒指数",
"level":"少发",
"prompt":"各项气象条件适宜,发生感冒机率较低。但请避免长期处于空调房间中,以防感冒。"
},
"tr":{
"expName":"旅游指数",
"level":"较适宜",
"prompt":"天气较好,温度较高,天气较热,但有微风相伴,还是比较适宜旅游的,不过外出时要注意防暑防晒哦!"
},
"uv":{
"expName":"紫外线强度指数",
"level":"中等",
"prompt":"属中等强度紫外线辐射天气,外出时建议涂擦SPF高于15、PA+的防晒护肤品,戴帽子、太阳镜。"
},
"xc":{
"expName":"洗车指数",
"level":"不宜",
"prompt":"不宜洗车,未来24小时内有雨,如果在此期间洗车,雨水和路上的泥水可能会再次弄脏您的爱车。"
},
"yd":{
"expName":"运动指数",
"level":"适宜",
"prompt":"天气较好,赶快投身大自然参与户外运动,尽情感受运动的快乐吧。"
}
},
"humidity":"51%",
"img":"http://aiui-res.ufile.ucloud.com.cn/weather/01.png",
"lastUpdateTime":"2018-08-10 11:00",
"pm25":"28",
"temp":33,
"tempHigh":"33℃",
"tempLow":"25℃",
"tempRange":"25℃ ~ 33℃",
"warning":"",
"weather":"多云转雷阵雨",
"weatherDescription":"气温较高,请尽量避免午后高温时段的户外活动。",
"weatherDescription3":"24℃到33℃,今天到后天有雨,风不大,气温较高,请尽量避免午后高温时段的户外活动。",
"weatherDescription7":"22℃到33℃,今天到14号有雨,风不大,有点热,适合穿短袖短裙等夏季清凉衣物。",
"weatherType":1,
"week":"周五",
"wind":"南风微风",
"windLevel":0
},
{
"city":"北京",
"date":"2018-08-11",
"dateLong":1533916800,
"date_for_voice":"明天",
"img":"http://aiui-res.ufile.ucloud.com.cn/weather/04.png",
"lastUpdateTime":"2018-08-10 11:00",
"tempHigh":"30℃",
"tempLow":"24℃",
"tempRange":"24℃ ~ 30℃",
"weather":"雷阵雨转中雨",
"weatherDescription":"有点热,适合穿短袖短裙等夏季清凉衣物。",
"weatherType":4,
"week":"周六",
"wind":"东风微风",
"windLevel":0
},
{
"city":"北京",
"date":"2018-08-12",
"dateLong":1534003200,
"date_for_voice":"后天",
"img":"http://aiui-res.ufile.ucloud.com.cn/weather/04.png",
"lastUpdateTime":"2018-08-10 11:00",
"tempHigh":"30℃",
"tempLow":"24℃",
"tempRange":"24℃ ~ 30℃",
"weather":"雷阵雨",
"weatherDescription":"有点热,适合穿短袖短裙等夏季清凉衣物。",
"weatherType":4,
"week":"周日",
"wind":"东南风微风",
"windLevel":0
},
{
"city":"北京",
"date":"2018-08-13",
"dateLong":1534089600,
"date_for_voice":"13号",
"img":"http://aiui-res.ufile.ucloud.com.cn/weather/04.png",
"lastUpdateTime":"2018-08-10 11:00",
"tempHigh":"30℃",
"tempLow":"24℃",
"tempRange":"24℃ ~ 30℃",
"weather":"雷阵雨转多云",
"weatherDescription":"有点热,适合穿短袖短裙等夏季清凉衣物。",
"weatherType":4,
"week":"下周一",
"wind":"东北风微风",
"windLevel":0
},
{
"city":"北京",
"date":"2018-08-14",
"dateLong":1534176000,
"date_for_voice":"14号",
"img":"http://aiui-res.ufile.ucloud.com.cn/weather/01.png",
"lastUpdateTime":"2018-08-10 11:00",
"tempHigh":"32℃",
"tempLow":"24℃",
"tempRange":"24℃ ~ 32℃",
"weather":"多云转雷阵雨",
"weatherDescription":"气温较高,请尽量避免午后高温时段的户外活动。",
"weatherType":1,
"week":"下周二",
"wind":"东南风微风",
"windLevel":0
},
{
"city":"北京",
"date":"2018-08-15",
"dateLong":1534262400,
"date_for_voice":"15号",
"img":"http://aiui-res.ufile.ucloud.com.cn/weather/01.png",
"lastUpdateTime":"2018-08-10 11:00",
"tempHigh":"30℃",
"tempLow":"23℃",
"tempRange":"23℃ ~ 30℃",
"weather":"多云转晴",
"weatherDescription":"有点热,适合穿短袖短裙等夏季清凉衣物。",
"weatherType":1,
"week":"下周三",
"wind":"东风微风",
"windLevel":0
},
{
"city":"北京",
"date":"2018-08-16",
"dateLong":1534348800,
"date_for_voice":"16号",
"img":"http://aiui-res.ufile.ucloud.com.cn/weather/00.png",
"lastUpdateTime":"2018-08-10 11:00",
"tempHigh":"31℃",
"tempLow":"22℃",
"tempRange":"22℃ ~ 31℃",
"weather":"晴转多云",
"weatherDescription":"气温较高,请尽量避免午后高温时段的户外活动。",
"weatherType":0,
"week":"下周四",
"wind":"北风微风",
"windLevel":0
}
]
},
"dialog_stat":"DataValid",
"rc":0,
"save_history":true,
"semantic":[
{
"intent":"QUERY",
"slots":[
{
"name":"datetime",
"normValue":"{"datetime":"2018-08-11","suggestDatetime":"2018-08-11"}",
"value":"明天"
},
{
"name":"location.city",
"normValue":"北京市",
"value":"北京市"
},
{
"name":"location.cityAddr",
"normValue":"北京",
"value":"北京"
},
{
"name":"location.type",
"normValue":"LOC_BASIC",
"value":"LOC_BASIC"
},
{
"name":"queryType",
"value":"内容"
},
{
"name":"subfocus",
"value":"天气状态"
}
]
}
],
"service":"weather",
"sid":"atn005b5017@dx00070ec890d8a11001",
"state":{
"fg::weather::default::default":{
"state":"default"
}
},
"text":"明天北京的天气怎么样",
"used_state":{
"state":"default",
"state_key":"fg::weather::default::default"
},
"uuid":"atn005b5017@dx00070ec890d8a11001"
},
"result_id":2
}
],
"desc":"success",
"sid":"ara0012df9d@dx6f490ec890d70c4000"
}
# 错误码
错误码 | 描述 | 说明 | 处理方式 |
---|---|---|---|
0 | success | 成功 | |
10105 | illegal access | 没有权限 | 检查apiKey,ip,checkSum等授权参数是否正确 |
10106 | invalid parameter | 无效参数或参数值为空 | 上传必要的参数, 检查参数格式以及编码 |
10107 | illegal parameter | 非法参数值 | 检查参数值是否超过范围或不符合要求 |
10109 | illegal data length | 数据长度非法 | 检查上传数据长度是否超过限制 |
10110 | no license | 无授权许可 | 提供请求的 appid、 auth_id 向服务商反馈 |
10114 | time out | 超时 | 检查客户端时间是否正确,检测网络连接是否正常或提供sid给讯飞协助排查 |
10700 | engine error | 引擎错误 | 提供接口返回值,向服务商反馈 |
11004 | server up error | 服务请求上线错误 | 提供接口返回值,向服务商反馈 |
10202 | websocket connect error | 套接字连接异常 | 提供接口返回值,向服务商反馈 |
10204 | websocket write error | 网络数据包发送异常 | 提供接口返回值,向服务商反馈 |
10205 | websocket read error | 网络数据包接收异常 | 提供接口返回值,向服务商反馈 |
10301 | parse data error | 解析数据异常 | 提供接口返回值,向服务商反馈 |
10302 | package data error | 构建数据异常 | 提供接口返回值,向服务商反馈 |
11201 | appid authorize number not enough | 每秒交互次数超过上限 | 确认接口每秒交互次数是否超过限制(默认为20) |
# 调用示例
python脚本示例(python版本2.7.6)
说明:将脚本中 AUDIO_PATH、APPID、API_KEY参数替换成相应的音频路径、讯飞开放平台应用的 appid 及对应的 apiKey 即可,运行脚本可打印相应结果。
#-*- coding: utf-8 -*-
import requests
import time
import hashlib
import base64
URL = "http://openapi.xfyun.cn/v2/aiui"
APPID = ""
API_KEY = ""
AUE = "raw"
AUTH_ID = "2894c985bf8b1111c6728db79d3479ae"
DATA_TYPE = "audio"
SAMPLE_RATE = "16000"
SCENE = "main"
RESULT_LEVEL = "complete"
LAT = "39.938838"
LNG = "116.368624"
#个性化参数,需转义
PERS_PARAM = "{\\\"auth_id\\\":\\\"2894c985bf8b1111c6728db79d3479ae\\\"}"
FILE_PATH = ""
def buildHeader():
curTime = str(int(time.time()))
param = "{\"result_level\":\""+RESULT_LEVEL+"\",\"auth_id\":\""+AUTH_ID+"\",\"data_type\":\""+DATA_TYPE+"\",\"sample_rate\":\""+SAMPLE_RATE+"\",\"scene\":\""+SCENE+"\",\"lat\":\""+LAT+"\",\"lng\":\""+LNG+"\"}"
#使用个性化参数时参数格式如下:
#param = "{\"result_level\":\""+RESULT_LEVEL+"\",\"auth_id\":\""+AUTH_ID+"\",\"data_type\":\""+DATA_TYPE+"\",\"sample_rate\":\""+SAMPLE_RATE+"\",\"scene\":\""+SCENE+"\",\"lat\":\""+LAT+"\",\"lng\":\""+LNG+"\",\"pers_param\":\""+PERS_PARAM+"\"}"
paramBase64 = base64.b64encode(param)
m2 = hashlib.md5()
m2.update(API_KEY + curTime + paramBase64)
checkSum = m2.hexdigest()
header = {
'X-CurTime': curTime,
'X-Param': paramBase64,
'X-Appid': APPID,
'X-CheckSum': checkSum,
}
return header
def readFile(filePath):
binfile = open(filePath, 'rb')
data = binfile.read()
return data
r = requests.post(URL, headers=buildHeader(), data=readFile(FILE_PATH))
print(r.content)
← 微信接入文档 WebSocket 接口文档 →