## 产品概述
#### 简介
图灵机器人API是在人工智能的核心能力（包括语义理解、智能问答、场景交互、知识管理等）的基础上，为广大开发者、合作伙伴和企业提供的一系列基于云计算和大数据平台的在线服务和开发接口。
开发者可以利用图灵机器人的API创建各种在线服务，灵活定义机器人的属性、编辑机器人的智能问答内容，打造个人专属智能交互机器人，也支持多渠道（微信公众平台、QQ聊天）的快速接入。
#### 产品特色
图灵机器人平台是国内第一家个性化智能机器人开放平台，为广大开发者提供智能机器人API端口。图灵机器人基于DeepQA深度问答技术，对中文的识别准确率高达90%，是目前中文语境下智能度最高的机器人。图灵机器人具有高智能、一键接入、个性化、跨平台四大特点，通过图灵机器人开放平台，任何人都可以方便快捷的为微信公众号、微博、QQ群、WEB网站、智能客服系统以及智能家居系统、智能车载系统等软硬件领域接入一位聪明的图灵机器人。
#### 功能介绍
智能对话、私有语料库、技能服务是图灵机器人三大核心功能。智能对话是指，图灵机器人可赋予软硬件产品中文自然语言交互的能力；私有语料库是指图灵机器人用户可为机器人导入独家内容以满足个性化及商业化需要；技能服务是指，图灵机器人打包提供超30种实用生活服务技能，涵盖生活、出行、学习、金融、购物等多个领域，一站式满足用户需求。
#### 应用场景
图灵机器人应用广泛，目前已应用于实体机器人，如家用服务机器人、儿童陪伴机器人等，虚拟机器人，如智能客服系统、微信公众号、QQ机器人、APP应用等，智能家居控制系统、智能车载等领域。已为超30万合作方提供技术支持。
## 使用说明
#### 使用流程
###### 获取APIKEY
每一个激活用户都可以通过图灵机器人开放平台获取多个APIKEY（当前每个用户可最多获取5个APIKEY），用户可以根据自己的需要获取不同的图灵APIKEY来应用于多种场景，获取成功后就等于拿到了开启图灵服务的钥匙。
登入图灵账号，在机器人管理列表中即可看到每一个机器人的API KEY，如下图所示：
](images/screenshot_1519647972142.png)
#### 编码方式
UTF-8（调用图灵API的各个环节的编码方式均为UTF-8）
#### 接口地址
http://openapi.tuling123.com/openapi/api/v2
#### 请求方式
HTTP POST
#### 请求参数
请求参数格式为 json
请求示例：
~~~
{
"reqType":0,
"perception": {
"inputText": {
"text": "附近的酒店"
},
"inputImage": {
"url": "imageUrl"
},
"selfInfo": {
"location": {
"city": "北京",
"province": "北京",
"street": "信息路"
}
}
},
"userInfo": {
"apiKey": "",
"userId": ""
}
}
~~~
>参数说明
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
| --- | --- | --- | --- | --- |
| reqType | int | N | - | 输入类型:0-文本(默认)、1-图片、2-音频 |
| perception | - | Y | - | 输入信息 |
| userInfo | - | Y | - | 用户参数 |
**perception**
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
| --- | --- | --- | --- | --- |
| inputText | - | N | - | 文本信息 |
| inputImage | - | N | - | 图片信息 |
| inputMedia | - | N | - | 音频信息 |
| selfInfo | - | N| - | 客户端属性 |
注意：输入参数必须包含inputText或inputImage或inputMedia！
***inputText***
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
| --- | --- | --- | --- | --- |
| text | String | Y | 1-128字符 | 直接输入文本 |
***inputImage***
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
| --- | --- | --- | --- | --- |
| url | String | Y | | 图片地址 |
***inputMedia***
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
| --- | --- | --- | --- | --- |
| url | String | Y | | 音频地址 |
***selfInfo***
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
| --- | --- | --- | --- | --- |
| location | - | N | - | 地理位置信息 |
*****location*****
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
| --- | --- | --- | --- | --- |
| city | String | Y | - | 所在城市 |
| province | String | N | - | 省份 |
| street | String | N | - | 街道 |
**userInfo**
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
| --- | --- | --- | --- | --- |
| apiKey | String | Y | 32位 | 机器人标识 |
| userId | String | Y | 长度小于等于32位 | 用户唯一标识 |
| groupId | String | N| 长度小于等于64位 | 群聊唯一标识 |
| userIdName | String | N | 长度小于等于64位 | 群内用户昵称 |
#### 输出参数
输出示例：
~~~
{
"intent": {
"code": 10005,
"intentName": "",
"actionName": "",
"parameters": {
"nearby_place": "酒店"
}
},
"results": [
{
"groupType": 1,
"resultType": "url",
"values": {
"url": "http://m.elong.com/hotel/0101/nlist/#indate=2016-12-10&outdate=2016-12-11&keywords=%E4%BF%A1%E6%81%AF%E8%B7%AF"
}
},
{
"groupType": 1,
"resultType": "text",
"values": {
"text": "亲，已帮你找到相关酒店信息"
}
}
]
}
~~~
>参数说明
| 参数 | 类型 | 是否必须 | 取值范围 | 说明 |
| --- | --- | --- | --- | --- |
| intent | - | Y | - | 请求意图 |
| results | - | N | - | 输出结果集 |
**intent**
| 参数 | 类型 | 是否包含 | 取值范围 | 说明 |
| --- | --- | --- | --- | --- |
| code | int | Y | - | 输出功能code |ap
| intentName | String | N | - | 意图名称 |
| actionName | String | N | - | 意图动作名称 |
| parameters | Map | N | - | 功能相关参数 |
**results**
| 参数 | 类型 | 是否包含 | 取值范围 | 说明 |
| --- | --- | --- | --- | --- |
| resultType | String | Y | 文本(text);连接(url);音频(voice);视频(video);图片(image);图文(news)| 输出类型 |
| values | - | Y | - | 输出值 |
| groupType | int | Y | - | ‘组’编号:0为独立输出，大于0时可能包含同组相关内容 (如：音频与文本为一组时说明内容一致)|
#### 异常返回码
###### 异常返回格式
~~~
{
'intent':
{
'code':5000
}
}
~~~
###### 异常返回说明
| 异常码 | 说明 |
| --- | --- |
| 5000 | 无解析结果 |
| 6000 | 暂不支持该功能 |
| 4000 | 请求参数格式错误 |
| 4001 | 加密方式错误 |
| 4002 | 无功能权限 |
| 4003 | 该apikey没有可用请求次数 |
| 4005 | 无功能权限 |
| 4007 | apikey不合法 |
| 4100 | userid获取失败 |
| 4200 | 上传格式错误 |
| 4300 | 批量操作超过限制 |
| 4400 | 没有上传合法userid |
| 4500 | userid申请个数超过限制 |
| 4600 | 输入内容为空 |
| 4602 | 输入文本内容超长(上限150)|
| 7002 | 上传信息失败 |
| 8008 | 服务器错误 |
| 0 | 上传成功 |
## 常见问题
Q：图灵APIKEY怎么获取？
A：注册登入图灵官网www.tuling123.com后，在机器人管理列表中即可看到每一个机器人的APIKEY，获取APIKEY后就等于找到了开启图灵服务的钥匙，用户可以根据自己的需要自行选择使用场景。
Q：为什么机器人总是会学我说话？
A：当您的机器人找不到答案的时候，它就会进入到“无答案”的功能设置中。此时免费版和标准版有不同的使用权限。免费版中返回结果只能是学用户说话，标准版除了可以在“无答案”时使用学用户说话模式，也可以自定义”无答案“时的内容。例如：您未在能力商城中获取并开启“天气查询”功能，当您查询天气时，此时就会处于“无答案”的状态，机器人则会根据用户的等级和设置进行相应的回答。
Q：为什么官网后台页面有时点击按钮没有反应？
A：可能是因为浏览器版本过低导致的，建议您使用主流的浏览器或将浏览器进行升级，目前图灵机器人对IE8及以下浏览器不进行兼容支持。
Q：使用WEB API调用接口后，为什么返回的结果会是类似“不明白您说的意思”？
A：出现这类情况，有可能是编码格式不统一导致的，图灵机器人的接口编码统一采用UTF-8格式。建议您将所有的编码格式换成UTF-8。
