[TOC] ## **一、合作商说明** 图灵机器人合作商接口主要针对开发者及企业用户开放,方便开发者及企业用户通过接口的方式对机器人进行批量生成、管理及日常查询等操作。 ## **二、功能说明** **合作商账号功能包含“合作商管理页”及“合作商接口文档”** **合作商管理后台** 可对接口生成的机器人进行查看、升级、管理。 **合作商接口文档** 开放了“机器人创建管理模块”,“语料库增删改查模块”、“娱乐技能控制模块”三大模块接口。 --- ### ****1.合作商管理后台**** #### **基础信息页** **可开通机器人个数:** 当前合作商账号最多可创建100个机器人,若需要更高创建机器人权限可与图灵机器人联系付费购买; **服务到期时间:** 服务使用时间默认为1年,若服务即将到期可与图灵机器人联系延长使用期限; **剩余调用次数:** 即为当前所有子机器人剩余可调用的次数; **今日合计调用次数:** 所有子机器人当日总调用次数; #### **机器人管理页** **日最大调用次数:** 该机器人每日最大调用次数,可通过权限升级接口增加调用量。 **累计调用量:**该机器人自创建以来累积调用次数; **今日调用量:** 该机器人当日调用次数; **操作:** “禁用”则该机器人无法使用,“启用”则该机器人恢复使用; --- ### ****2.合作商接口文档**** #### ****机器人创建管理模块**** **(1)批量生成:** 可通过合作商接口批量生成多个机器人。 **(2)多级账户:** 多级账户由父账号和子机器人组成,父账号有机器人管理权,子机器人可用聊天对话、语料库、生活技能等服务。 **(3)权限分配:** 合作商可根据用户业务需求,分配或升级子机器人的调用量、语料内容、技能数量等使用权限。 **(4)属性自定义:** 开放机器人属性自定义接口,可让用户自己修改姓名、性别、年龄、爸爸妈妈等个性化属性。 #### ****语料库增删改查模块**** **(1)语料导入:** 可通过接口在语料库中批量上传问题、答案及相似问题等内容。 **(2)语料删改:** 可对语料库已有内容进行查询、删除、修改。 **(3)匹配度设置:** 可对语料库相似度匹配阈值进行调控,让用户自主选择“完全匹配”或“模糊匹配”模式。 #### ****娱乐技能控制模块**** 开放24个生活技能,合作商可通过接口控制各个机器人的技能开关。 ## **三、接口说明** ### ****1.接口约定**** #### ****传输格式**** JSON #### ****编码方式**** UTF-8(调用图灵API的各个环节的编码方式均为UTF-8) #### ****指定header**** Content-Type 为 application/json #### ****请求方式**** HTTP POST #### ****统一返回错误码**** | 异常码 | 说明 | | --- | --- | |3\*\* |操作错误 | |301 |缺少必要参数,参数格式错误 | |4\*\* |权限错误 | |401 |APIkey不存在或不具有权限 | |5\*\* |接口传输错误| ### ****2.机器人管理接口**** #### ****2.1机器人创建**** (1)请求接口 http://www.tuling123.com/v1/robot/create (2)请求数据 ``` { "user": "user", "data": { "name":"小灵儿", "level": 1, "faq": 1000, "match": 70 } } ``` (3)请求数据 | 参数 | 类型 | 是否必须 |说明 | --- | --- | --- | --- | --- | |user|string|Y|用户名| |name|string|Y| 机器人名称 | |level|int|Y| 机器人每日调用上限(整数*1000次)| |faq|int|N| 知识库存储总量| |match|int|N| 知识库匹配度| (4)返回数据 ``` { "code": 0, "data": { "apikey": "apikey", "level": 1, "faq": 1000, "name": "小灵儿", "match": 70 } } ``` #### ****2.2机器人权限升级**** (1)请求接口 http://www.tuling123.com/v1/robot/upgrate (2)请求数据 ``` { "apikey":"apikey", "data":{ "level":1, "faq":2000 } } ``` (3)参数说明 | 参数 | 类型 | 是否必须 | 说明 | | --- | --- | --- | --- | --- | |apikey|string|Y| 机器人Apikey | |level|string|Y| 机器人每日调用上限(整数*1000次) | |faq|int|N| 知识库匹配度| (4)返回数据 ``` { code: 0, data:{ "level":level, "faq":faq } } ``` #### ****2.3机器人属性设置**** (1)请求接口 http://www.tuling123.com/v1/robot/profile (2)请求数据 ``` { "apikey": " apikey ", "data": { "nickname": "hellorobot", "gender": "F/M", "age": 22, "image": "http://图像地址", "father": "father", "mother": "mother" } } ``` (3)参数说明 | 参数 | 类型 | 是否必须 | 说明 | | --- | --- | --- | --- | --- | |apikey|string|Y|机器人apikey| |nickname|string|N|机器人昵称| |gender|string|N|性别(男M,女F)| |age|int|N|年龄| |image|string|N|头像(url)| |father|string|N|爸爸名字| |mother|string|N|妈妈名字| (4)返回数据 ``` { "code": 0, "data": { "nickname": "", "gender": "F/M", "age": 22, "image": "http://图像地址", "father": "father", "mother": "mother" } } ``` #### ****2.4机器人信息查询**** (1)请求接口 http://www.tuling123.com/v1/robot/info (2)请求数据 ``` { "apikey":" apikey " } ``` (3)参数说明 | 参数 | 类型 | 是否必须 | 说明 | | --- | --- | --- | --- | --- | |apikey|string|Y|机器人apikey| (4)返回数据 ``` { code:0, data:{ "faq":{}, "robotSetting":{}, "ability":{} } } ``` ### ****3.语料库管理接口**** #### ****3.1语料库匹配度**** (1)请求接口 http://www.tuling123.com/v1/kb/match (2)请求数据 ``` { "apikey":" apikey ", "data":{ "match":60 } } ``` (3)参数说明 | 参数 | 类型 | 是否必须 | 说明 | | --- | --- | --- | --- | --- | |apikey|string|Y|机器人apikey| |match|int|Y|语料库匹配度| (4)返回数据 ``` { code: 0, data:{ "match":60 } } ``` #### ****3.2语料库新增**** (1)请求接口 http://www.tuling123.com/v1/kb/import (2)请求数据 ``` { "apikey":" apikey ", "data":{ "list":[ {"question":"question", "answer":"answer", "simiQuestion":["simiQuestion1","simiQuestion2","simiQuestion3"] }] } } ``` (3)参数说明 | 参数 | 类型 | 是否必须 | 说明 | | --- | --- | --- | --- | --- | |apikey|string|Y|机器人apikey| |question|string|Y|问题| |answer|string|Y|答案| |simiQuestion|array|N|相似问题| (4)返回数据 ``` { "code": 0, "data": { "successNum": 1, "knowledgeList": [ { "answer": "answer", "question": "question", "id": "2146008", "time": "2016-10-17 11:14:38", "label_id": 0, } ] } } ``` #### ****3.3语料库修改**** (1)请求接口 http://www.tuling123.com/v1/kb/update (2)请求数据 ``` { "apikey":" apikey ", "data":{ "list":[ { "id":"1", "question":"question", "answer":"answer", "simiQuestion":["新相似问题","新相似问题"]} ] } } ``` (3)参数说明 | 参数 | 类型 | 是否必须 | 说明 | | --- | --- | --- | --- | --- | |apikey|string|Y|机器人apikey| |id|int|Y|数据id| |question|string|N|新的问题| |answer|string|N|新的答案| |simiQuestion|array|N|新的相似问题| (4)返回数据 ``` { "code":0, "data": { "successNum": 2 } } ``` #### ****3.4语料库删除**** (1)请求接口 http://www.tuling123.com/v1/kb/delete (2)请求数据 ``` { "apikey": "apikey", "data": { "clear": false, "ids": [1,2,3] } } ``` (3)参数说明 目前支持两种形式的删除接口。 1)如果有"clear"的字段而且 clear 的布尔值为 true,则执行清空操作; 2)第二种会根据用户传过来的 ids 中 json 数组里面的 id,删除对应的记录; | 参数 | 类型 | 是否必须 | 说明 | | --- | --- | --- | --- | --- | |apikey|string|Y|机器人apikey| |clear|bool|Y|是否执行清空| |ids|array|N|待删除的问题id| (4)返回数据 ``` { "code":0, "data":"3" } ``` #### ****3.5语料库查询**** (1)请求接口 http://www.tuling123.com/v1/kb/select (2)请求数据 ``` { "apikey":" apikey ", "data": { "pages":{ "pageNumber":1, "pageSize":10, "searchBy": "question" } } } ``` (3)参数说明 | 参数 | 类型 | 是否必须 | 说明 | | --- | --- | --- | --- | --- | |apikey|string|Y|机器人apikey| |pageNumber|int|Y|页数| |pageSize|int|Y|每页显示行数| |searchBy|string|Y|查询的关键词| (4)返回数据 ``` { "code": 0, "data": { "totalCount": 2, "knowledgeCount": 2, "knowledgeList": [{ "id": "2", "simiQuestion": ["相似问题 1","相似问题 2","相似问题 3" ], "time": "2017-02-15 10:14:25", "answer": "answer2", "state": 1, "label_id": 0, "question": "question2" }] } } ``` ### ****4.机器人技能接口**** (1)请求接口 http://www.tuling123.com/v1/robot/ability (2)请求数据 ``` { "apikey": " apikey ", "data": { "list": [{ "news": false } ] } } ``` (3)参数说明 | 参数 | 类型 | 是否必须 | 说明 | | --- | --- | --- | --- | --- | |apikey|string|Y|机器人apikey| |list|array|Y|功能及其开关操作列表| (4)功能名称对应表 | 功能名称| 英文名称| | --- | --- | --- | --- | --- | --- | |数字计算|number_count| |图片搜索|picture| |问答百科|question_answer| |语料库|knowledgebase| |中英互译 |translation| |聊天对话|chat| |笑话大全 |joke| |故事大全|story| |成语接龙 | idiom_game| |新闻资讯 |news| |星座运势|constellation| |脑筋急转弯|brain_twists| |歇后语| xiehouyu| |绕口令|tongue_twister| |顺口溜|jingle| |天气查询|weather| |菜谱大全|cookbook| |快递查询|express| |列车查询|train| |日期查询|date| |附近酒店|nearby_hotel| |汽油报价|oil_price| |股票查询|share_search| |城市邮编|postcode| (5)返回数据 ``` { code:0, data:{ list:[ {"appname":true/false}, {"appname":true/false} ] } } ```