# 接口说明

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

# 示例代码

Github V2 (opens new window)

# 接口地址

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-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)