开发文档

1、简介

AIUI 通过 REST API 的方式给开发者提供一个通用的 HTTP 接口,基于该接口,开发者可以轻松的获取AIUI 的语音识别,语音语义以及文本语义的能力,方便开发者使用自己熟悉的编程语言快速集成。

2、接口概述

2.1 API说明

1、授权认证,调用接口需要将APPID,CurTime, Param和CheckSum信息放在HTTP请求头中。

2、所有接口统一为UTF-8编码。

3、所有接口支持http和https。

2.2 授权认证

在调用所有业务接口时,都需要在Http Request Header中加入以下参数作为授权验证:

参数 说明 是否必须
X-Appid 讯飞开放平台注册申请应用的应用ID(APPID)
X-CurTime 当前UTC时间戳,从1970年1月1日0点0 分0 秒开始到现在的秒数(String)
X-Param Base64编码的json,见接口详细说明
X-CheckSum MD5(ApiKey + CurTime + Param + http_body),四个参数拼接的字符串,
进行MD5哈希计算。其中http_body 即为请求服务的实际服务HTTP body

注:

1、CheckSum有效期:出于安全性考虑,每个CheckSum的有效期为5分钟(用curTime计算),同时CurTime要与标准时间同步,否则,时间相差太大,服务端会直接认为CurTime无效。

2、ApiKey创建应用时自动生成,第三方注意保管,如果泄露,可在页面中进行重置。

3、CheckSum生成示例

例如:

ApiKey是abcd1234, CurTime是1502607694,Param是eyJzY2VuZSI6Im1haW4ifQ==, http_body是text=5LuK5aSp5pif5pyf5Yeg。

那么CheckSum为MD5(abcd12341502607694eyJzY2VuZSI6Im1haW4ifQ==text=5LuK5aSp5pif5pyf5Yeg)

2.3 IP 白名单

在调用所有业务接口时,授权认证通过后。检查调用方ip是否在aiui开放平台配置的ip白名单中。存在通过,否则拒绝提供服务。

注:拒绝提供服务返回值:{"code":"20004","desc":"ip非法","data":null}

2.4 通用请求地址

base_url:api.xfyun.cn

3、AIUI接口

3.1 接口说明

3.1.1 通用返回参数

参数 说明 是否必须
code 结果码
data 返回结果
desc 描述

3.2 文本语义接口

3.2.1 接口描述

本接口对用户的文本进行解释分析,返回文本的语义意图。

3.2.2 接口地址

POST /v1/aiui/v1/text_semantic HTTP/1.1
Content-Type:application/x-www-form-urlencoded; charset=utf-8

3.2.3 参数说明

在调用本接口时,需要在Http Request Header中加入参数X-Param

参数 类型 必须 说明 示例
X-Param Base64编码的json 标准JSON格式参数
需把参数组装json对象,
然后对json进行base64编码
json: {"scene":"main"}
base64编码: eyJzY2VuZSI6Im1haW4ifQ==

X-Param参数说明:

参数 类型 必须 说明 示例
scene String 情景模式 main
userid String 用户 id,适用于多轮对话。 user_0001

Http Request Body中加入以下参数:

参数 类型 必须 说明 示例
text String 文本 今天星期几
base64编码:5LuK5aSp5pif5pyf5Yeg

3.2.4 返回说明

返回结果data如下:

参数 类型 必须 说明
rc int 应答码(response code)
text String 用户的输入,可能和请求中的原始text不完全一致,因服务器可能会对text进行语言纠错
vendor String 技能提供者,不存在时默认表示为IFLYTEK提供的开放技能
service String 技能的全局唯一名称,一般为vendor.name,vendor不存在时默认为IFLYTEK提供的开放技能。
semantic Array 本次语义(包括历史继承过来的语义)结构化表示,各技能自定义
data Object 数据结构化表示,各技能自定义
answer Object 对结果内容的最简化文本/图片描述,各技能自定义
dialog_stat String 用于客户端判断是否使用信源返回数据
moreResults Object 在存在多个候选结果时,用于提供更多的结果描述
sid String 本次服务唯一标识

3.2.5 curl示例

请求:
curl –XPOST http[s]://base_url/v1/aiui/v1/text_semantic -H "X-Appid: 594b62c3 "
-H "X-CurTime: 1502610698" -H "X-CheckSum: 3c22f7c07620776172675c7143c33026"
-H "X-Param: eyJzY2VuZSI6Im1haW4ifQ==" -d "text=5LuK5aSp5pif5pyf5Yeg"
响应体:
{
  "code": "00000",
  "desc": "成功",
  "data": {
    "answer": {
      "text": "今天是2017年08月08日 丁酉年六月十七 星期二",
      "type": "T"
    },
    "match_info": {
      "type": "gparser_path",
      "value": "-----"
    },
    "operation": "ANSWER",
    "rc": 0,
    "service": "datetime",
    "text": "今天星期几",
    "uuid": "atn00210ce6@un782b0ce4cac76f2601",
    "sid": "atn00210ce6@un782b0ce4cac76f2601"
  }
}

3.3 语音识别接口

3.3.1 接口描述

本接口将自然语言识别为文本输出。

注:语音识别最大支持60秒

3.3.2 接口地址

POST /v1/aiui/v1/iat HTTP/1.1
Content-Type:application/x-www-form-urlencoded; charset=utf-8

3.3.3 参数说明

在调用本接口时,需要在Http Request Header中加入参数X-Param。

参数 类型 必须 说明 示例
X-Param Base64编码的json 标准JSON格式参数。
需按照参数示例组装json对象,
然后对json进行base64编码
json: {"auf":"8k","aue":"raw","scene":"main"}
base64编码: eyJhdWYiOiI4ayIsImF1ZSI6InJhdyIsInNjZW5lIjoibWFpbiJ9

X-Param参数说明:

参数 类型 必须 说明 示例
auf String 音频格式 (audio/L16;rate=8000时取8k; audio/L16;rate=16000时取16k) 8k
aue String 音频编码(音频为未压缩的 pcm 或 wav 格式的音频时为raw) raw
scene String 情景模式 main

Http Request Body中加入以下参数:

参数 类型 必须 说明 示例
data String Base64 编码的音频, 支持 pcm 或 wav Base64编码内容(音频二进制): xxxxxxxxxxxxxxxxx

3.3.4 返回说明

返回结果data如下:

参数 类型 必须 说明
sid String 本次服务唯一标识
result String 音频对应的识别结果
ret int 错误码(0表示成功)

3.3.5 curl示例

请求:
curl –XPOST http[s]://base_url/v1/aiui/v1/iat -H "X-Appid: 594b62c3 " -H
"X-CurTime: 1502184180" -H "X-CheckSum: 001388491350e266fab5e15da9aea749" –H
"X-Param: eyJhdWYiOiI4ayIsImF1ZSI6InJhdyIsInNjZW5jZSI6Im1haW4ifQ==" –d
"data=PDXOSEarAABo6Ojo6Ojo6IOh9HR0cl8oFw9BVeNc2jFr2ZFfsszurkqtCWGbDVo4BbWtYr
VcURYFsaBzhzw1zOFgTIk3FRsH2E9tYG1N+YqGAPrFrJl70D2jrjK7UjHoKSsP1bxZ5TWiPqUqOh
IMMWGEB4GkIANo3Zc8Ndltx4vefwFWQWS00vNr3z++TcAi6Zs0A4vN3VWC4FDG2urTVuG3GSLfAo
9NujshWduRgGhAztDgLkw3PDHPLovLerbSod+ZLjopVprhgqHgi6a7F/P/w9NnTSpHeFKV+ibtpENr7miGWC…"
响应体:
{
    "code": "00000",
    "desc": "成功",
    "data": {
        "ret": 0,
        "result": "今天星期几。",
        "sid": "watb37fe700@ch47730ce51e04477300"
    }
}

3.4 语音语义接口

3.4.1 接口描述

本接口先将自然语言识别为文本,后对该文本进行解释分析,返回文本的语义意图。

3.4.2 接口地址

POST /v1/aiui/v1/voice_semantic HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8

3.4.3 参数说明

在调用本接口时,需要在Http Request Header中加入参数X-Param。

参数 类型 必须 说明 示例
X-Param Base64编码的json 标准JSON格式参数。
需按照参数示例组装json对象,
然后对json进行base64编码
json: {"auf":"8k","aue":"raw","scene":"main"}
base64编码: eyJhdWYiOiI4ayIsImF1ZSI6InJhdyIsInNjZW5lIjoibWFpbiJ9

X-Param参数说明:

参数 类型 必须 说明 示例
auf String 音频格式 (audio/L16;rate=8000时取8k; audio/L16;rate=16000时取16k) 8k
aue String 音频编码(音频为未压缩的 pcm 或 wav 格式的音频时为raw) raw
scene String 情景模式 main
userid String 用户 id,适用于多轮对话。 user_0001

Http Request Body中加入以下参数:

参数 类型 必须 说明 示例
data String Base64 编码的音频,支持 pcm 或 wav Base64编码内容(音频二进制): xxxxxxxxxxxxxxxxx

3.4.4 返回说明

返回结果data如下:

参数 说明 是否必须
code 结果码
data 返回结果
desc 描述
iat_code 识别结果码

返回结果data如下:

参数 类型 必须 说明
rc int 应答码(response code)
text String 用户的输入,可能和请求中的原始text不完全一致,因服务器可能会对text进行语言纠错
vendor String 技能提供者,不存在时默认表示为IFLYTEK提供的开放技能
service String 技能的全局唯一名称,一般为vendor.name,vendor不存在时默认为IFLYTEK提供的开放技能。
semantic Array 本次语义(包括历史继承过来的语义)结构化表示,各技能自定义
data Object 数据结构化表示,各技能自定义
answer Object 对结果内容的最简化文本/图片描述,各技能自定义
dialog_stat String 用于客户端判断是否使用信源返回数据
moreResults Object 在存在多个候选结果时,用于提供更多的结果描述
sid String 本次服务唯一标识

3.4.5 curl示例

请求:
curl –XPOST http[s]://base_url/v1/aiui/v1/iat -H "X-Appid: 594b62c3 " -H
"X-CurTime: 1502184180" -H "X-CheckSum: 001388491350e266fab5e15da9aea749" –H
"X-Param: eyJhdWYiOiI4ayIsImF1ZSI6InJhdyIsInNjZW5jZSI6Im1haW4ifQ==" –d
"data=PDXOSEarAABo6Ojo6Ojo6IOh9HR0cl8oFw9BVeNc2jFr2ZFfsszurkqtCWGbDVo4BbWtYr
VcURYFsaBzhzw1zOFgTIk3FRsH2E9tYG1N+YqGAPrFrJl70D2jrjK7UjHoKSsP1bxZ5TWiPqUqOh
IMMWGEB4GkIANo3Zc8Ndltx4vefwFWQWS00vNr3z++TcAi6Zs0A4vN3VWC4FDG2urTVuG3GSLfAo
9NujshWduRgGhAztDgLkw3PDHPLovLerbSod+ZLjopVprhgqHgi6a7F/P/w9NnTSpHeFKV+ibtpENr7miGWC…"
响应体:
{
  "code": "00000",
  "desc": "成功",
  "iat_code": "0",
  "data": {
    "answer": {
      "text": "今天是2017年08月08日 丁酉年六月十七 星期二",
      "type": "T"
    },
    "match_info": {
      "type": "gparser_path",
      "value": "-----"
    },
    "operation": "ANSWER",
    "rc": 0,
    "service": "datetime",
    "text": "今天星期几",
    "uuid": "atn00210ce6@un782b0ce4cac76f2601",
    "sid": "atn00210ce6@un782b0ce4cac76f2601"
  }
}
4、错误码

错误码信息如下表:

错误码 错误描述
00000 成功
10001 授权请求头参数为空
10002 过期请求
10003 无效的APPID
10004 TOKEN无效
10005 无权操作
10006 服务异常
20001 必选参数为空
20002 请求超时
20003 参数非法
20004 ip非法
20005 http消息体为空
20006 语音识别结果为空
99999 系统异常
5、常见问题

1. 音频格式 pcm 与wav 格式之间的关系。

pcm 几乎就是 wav 格式,内部存储音频方式是一样的。但 wav 比 pcm 多了一个很短的文件头用来告诉播放器所存储音频的采样频率,声道为单声道或立体声,一次采样使用的 bit 数等参数,故 wav 是可以在播放器中直接播放的,而 pcm 却不行。当用 Cool Edit 打开 pcm 音频时,选择的参数相当于临时确定了文件头,此时音频才可以播放。

2. 可以通过给 pcm 添加一个文件头,将 pcm 音频直接转换为 wav 格式。

语音识别接口中,每次都能返回文本,但为什么识别率却不高? 服务中,每次都能返回文本,但为什么识别率却不高?

首先请确保你的音频有一定的清晰度。

其次 WebAPI 所接收和返回的文本原始编码均为 utf-8,请查看你的编码设置。最后,请关注读取音频文本并进行 base64 加密的过程。要直接对整个文本进行 base64 加密。如果你用的是 C++,而且你是先把文本读到字符串中,再对字符串进行加密,就有可能出现字符串中只存储了部分音频(遇到文本中的'\0',字符串就结束了),致使所发送的音频信息缺失。