接口说明

AIUI是科大讯飞提供的一套人机智能交互解决方案, 旨在实现人机交互无障碍,使人与机器之间可以通过语音、图像、手势等自然交互方式,进行持续,双向,自然地沟通。

示例代码

Github V2

接口地址

POST https://openapi.xfyun.cn/v2/aiui HTTP/1.1

API说明

  1. 授权认证,调用接口需要将 Appid,CurTime, Param 和 CheckSum 信息放在 HTTP 请求头中;
  2. 接口统一为 UTF-8 编码;
  3. 接口支持 http 和 https;
  4. 请求方式为POST。

授权认证

在调用接口时,需要在 Http Request Header 中配置以下参数用于授权认证:

参数格式说明必须
X-Appidstring讯飞AIUI开放平台注册申请应用的应用ID(appid)
X-CurTimestring当前UTC时间戳,从1970年1月1日0点0 分0 秒开始到现在的秒数
X-Paramstring相关参数JSON串经Base64编码后的字符串,见各接口详细说明
X-CheckSumstring令牌,计算方法: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字段类型必须说明示例
scenestring情景模式(目前不支持 wpgs-识别动态修正 场景)main
auth_idstring用户唯一ID(32位字符串,包括英文小写字母与数字,开发者需保证该值与终端用户一一对应)2049a1b2fdedae553bd03ce6f4820ac4
data_typestring数据类型,可选值:text(文本),audio(音频)text
sample_ratestring音频采样率,可选值:16000(16k采样率)、8000(8k采样率),默认为1600016000
auestring音频编码,可选值:raw(未压缩的pcm或wav格式)、speex(speex格式,即sample_rate=8000的speex音频)、speex-wb(宽频speex格式,即sample_rate=16000的speex音频),默认为 rawraw
speex_sizestringspeex音频帧大小,speex音频必传。详见speex_size与speex库压缩等级关系表60
latstring纬度31.83
lngstring经度117.14
pers_paramstring个性化参数,json字符串,目前支持用户级(auth_id)、应用级(appid)和用户自定义级,不支持透传其他参数。"{"auth_id":"xxxxxx"}"
result_levelstring结果级别,可选值:plain(精简),complete(完整),默认 plainplain
interact_modestring是否开启云端vad,可选值:continuous(开启),oneshot(关闭),默认为 continuous,注意,开启后可能返回多个识别和语义结果continuous
topnstring多候选词2
client_ipstring设备终端IP,可用于定位,定位优先级:文本中地理位置>经纬度信息>设备终端IP61.191.24.236
clean_dialog_historystring是否清除交互历史,可选值:auto(不清除)、user(清除),默认为不清除user

speex_size与speex库压缩等级(quantity)关系表:

quantity(压缩等级)012345678910
speex610152020282838384662
speex-wb10152025324252607086106

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字段类型说明
codestring结果码(具体见错误码)
dataarray结果数据
descstring描述
sidstring会话ID

其中 sid 字段主要用于追查问题,如果出现问题,可以提供 sid 给讯飞技术人员帮助确认问题。

data 字段说明如下:

JSON字段类型说明
substring业务类型:iat(识别),nlp(语义),tpp(后处理),itrans(翻译)
textobject/string识别结果:详细结果(object),精简结果(string)
intentobject语义结果
contentobject/string后处理 (string),翻译 (object)等结果
result_idnumber结果序号,同一业务逐渐递增

text 详细结果字段说明:

JSON字段英文全称类型说明
snsentencenumber第几句
lslast sentenceboolean是否最后一句
bgbeginnumber开始
edendnumber结束
wswordsarray
cwchinese wordarray中文分词
wwordstring单字
scscorenumber分数

intent 字段说明:

详见 AIUI开放平台语义协议

content 字段说明:

若业务类型为 tpp (后处理),则为后处理接口返回的内容;若业务类型为 itrans (翻译),则为翻译结果 JSON 对象,其字段说明如下:

JSON字段类型说明
fromstring源语言语种
tostring目标语言语种
resultstring翻译的结果
srcstring源语言结果
dststring翻译的目标语言结果
sidstring翻译引擎sid
retnumber调用结果

接口调用返回值示例: 失败:

    {
      "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"
    }

错误码

错误码描述说明处理方式
0success成功
10105illegal access没有权限检查apiKey,ip,checkSum等授权参数是否正确
10106invalid parameter无效参数或参数值为空上传必要的参数, 检查参数格式以及编码
10107illegal parameter非法参数值检查参数值是否超过范围或不符合要求
10109illegal data length数据长度非法检查上传数据长度是否超过限制
10110no license无授权许可提供请求的 appid、 auth_id 向服务商反馈
10114time out超时检查客户端时间是否正确,检测网络连接是否正常或提供sid给讯飞协助排查
10700engine error引擎错误提供接口返回值,向服务商反馈
11004server up error服务请求上线错误提供接口返回值,向服务商反馈
10202websocket connect error套接字连接异常提供接口返回值,向服务商反馈
10204websocket write error网络数据包发送异常提供接口返回值,向服务商反馈
10205websocket read error网络数据包接收异常提供接口返回值,向服务商反馈
10301parse data error解析数据异常提供接口返回值,向服务商反馈
10302package data error构建数据异常提供接口返回值,向服务商反馈
11201appid 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)
AIUI文档中心