在线分词接口文档

文档状态

文件标识：	TuringOS-Segmentation-V1.0.1
系统版本：	API
完成日期：	2022年4月28日

文档修订记录

为便于后续文档维护，文档版本号将由三部分组成，第一个数字为主版本号，第二个数字为功能版本号，第三个数字为修订版本号：

文档版本号	修订日期	修订原因
V1.0.1	2021.4.23	创建文档

一、加密说明

为保证接口的安全性和稳定性，需要对接口数据进行加密；

加密必须包含的信息：APIkey，Secret（需通过图灵Biz平台 - 机器人信息页获取）；
需针对请求参数中的Data字段，进行AES加密处理，具体加密方式如下：

参数	说明	备注
加密模式	CBC	-
填充	PKCS5Padding	-
数据块	128位（密钥为16位）	-
密码	secretKey	Apikey+Secret+时间戳(毫秒，与入参保持一致) 进行Md5加密，取16位小写值
偏移量	secretKey	Apikey+Secret+时间戳(毫秒，与入参保持一致) 进行Md5加密，取16位小写值
输出	base64编码	-
字符集	utf-8	-

二、协议说明

1.在线分词接口

请求地址

正式环境：http://api.turingos.cn/tool/participle

请求方式：HTTP

Method: POST

Content-Type: application/json

请求示例

未开启加密模式请求示例：

{
    "data": {
        "deviceId":"ai00000000000001",
         "text": "我想听三国演义"
    },
    "key": "sofod***soisoge",
    "timestamp": "1543894585"
}

开启加密模式后请求示例：

{
  "data":"加密后的内容",
  "key":"ed474dae62*********67050faea1788",
  "timestamp":"150******7793"
}

data字段加密说明：

未开启加密模式请求示例：

{
        "deviceId":"ai00000000000001",
         "text": "我想听三国演义"
}

请求参数说明

参数	类型	是否必须	说明
key	String	Y	apiKey，需官网申请
timestamp	String	Y	时间戳
data	Json	Y	配置信息，加密后的请求数据，参考加密方式

data字段说明

参数	类型	是否必须	说明
deviceId	String	Y	用户设备Id: 由字母或数字组成，其他字符可能导致部分功能错误，长度等于16位
text	String	Y	分词文本

返回示例

{
    "code": 0,
    "value": [
        {
            "dataType": -1,
            "nature": "rr",
            "word": "我"
        },
        {
            "dataType": -1,
            "nature": "v",
            "word": "想"
        },
        {
            "dataType": -1,
            "nature": "v",
            "word": "听"
        },
        {
            "dataType": 1,
            "nature": "n_other",
            "subTerms": [
                {
                    "dataType": -1,
                    "nature": "m",
                    "word": "三"
                },
                {
                    "dataType": -1,
                    "nature": "n",
                    "word": "国"
                },
                {
                    "dataType": 1,
                    "nature": "n",
                    "subTerms": [
                        {
                            "dataType": -1,
                            "nature": "t_char",
                            "word": "演"
                        },
                        {
                            "dataType": -1,
                            "nature": "t_char",
                            "word": "义"
                        }
                    ],
                    "word": "演义"
                }
            ],
            "word": "三国演义"
        }
    ]
}

返回参数说明

参数	类型	是否必返	说明
code	int	Y	状态code； 0为正确 1为系统异常 2为业务数据校验失败 40008为初始化校验失败
value	array	Y	返回结果集合

value字段说明

参数	类型	是否必返	说明
dataType	int	Y	词的来源(可不处理) 0:未知-默认值 1:中文自定义词典 2:英文自定义词典 -1:不在中文和英文的自定义词典
nature	string	Y	词性
subTerms	Array	Y	下一层的更细粒度的分词结果集
word	string	Y	分词文本返回

value - subTerms字段说明

参数	类型	是否必返	说明
dataType	int	Y	词的来源(可不处理) 0:未知-默认值 1:中文自定义词典 2:英文自定义词典 -1:不在中文和英文的自定义词典
nature	String	Y	词性
word	String	Y	词

目前分词结果为多层嵌套结构：

1.当获取到分词结果时，可直接从第一层json中获取分词文本，如”我“，”想“，”听“，”三国演义“；

2.获取分词文本时，可在同层级json中判断是否有subTerms字段，若有subTerms字段，则代表首次分词结果可继续分词，如“三国”，“演义”；如没有subTerms字段，则代表不能继续分词。其他层级依次类推。

2.文本翻译接口

请求地址

正式环境： ws://ws-api.turingapi.com/api/v2

请求方式：WebSocket

端口号：80

字符编码：UTF-8

请求示例

文本请求翻译功能

加密后数据格式:

{
    "key": "ed474dae62*********67050faea1788",
    "timestamp": "150******7793",
    "data": "加密后的内容"
}

data加密前数据格式:

{
    "deviceId": "123",
    "requestType": ["NLP","TTS"],
    "nlpRequest": {
        "content": [{
            "data": "Hello World"
        }],
        "userInfo": {
            "useCodes": [1000018]
        }
    }
}

请求参数说明

参数	类型	是否必须	说明
key	String	Y	apiKey，需官网申请；
timestamp	String	Y	时间戳
data	Json	Y	配置信息，加密后的请求数据，加密参考：加密方式

data字段说明

参数	类型	是否必须	说明
deviceId	String	Y	用户设备Id: 由字母或数字组成，其他字符可能导致部分功能错误，长度等于16位。
requestType	Array	Y	该次请求需要请求的内容：0:ASR，1:NLP，2:TTS
nlpRequest	Json	Y	nlp内容请求信息 1：文本方式请求 2：图片、音频请求
binarysState	Json	N	二进制参数上传状态

nlpRequest - content字段说明（文本请求）

参数	类型	是否必须	说明
type	int	N	0：文本（默认，可不填写）
data	String	Y	文本信息

nlpRequest - userInfo字段说明

参数	类型	是否必须	说明
useCodes	Array	N	应用code [1000018]为指定请求全文翻译技能（输入内容不超过150个字)

返回示例

{
    "code": 200,
    "done": true,
    "globalId": "171156189262884001",
    "message": "success",
    "nlpResponse": {
        "intent": {
            "code": 100018
        },
        "results": [{
            "groupType": 0,
            "resultType": "text",
            "values": {
                "text": "hello"
            }
        }]
    }
}

返回参数说明

参数	类型	是否必须	说明
code	int	Y	状态code；参考状态code列表
globalId	String	Y	请求唯一标识，用于排查日志
message	String	Y	code对应的说明
nlpResponse	Json	N	nlp相关回复信息

nlpResponse - Intent字段说明

参数	类型	是否必须	说明
code	int	Y	输出应用code
operateState	int	Y	应用状态(应用单独定义)

nlpResponse - Result字段说明

参数	类型	是否必须	说明
resultType	String	Y	输出类型文本(text)；链接(url)；音频(voice)；动作表情(action)；视频(video)；图片(image)；图文(news)；
values	Map	Y	输出内容
groupType	int	Y	组类型(普通接入可忽略该参数) 0为独立输出；大于0时可能包含同组相关内容

附录：code状态列表

code	说明
200	正确结果返回
210	参数初始化成功，请收到该标识后上传二进制数据(如果需要)
220	参数上传完成，正在请求nlp/tts
240	输入参数为空，nlp/tts不处理
300	无效数据:二进制参数已完成传输，不要发送该数据
4004	机器人类型非法
4005	apikey信息错误
4006	deviceId信息错误
4007	解密失败，您的加密逻辑存在异常
4008	数据内容格式错误
4009	机器人被禁用
4010	试用期已过
4011	系统不支持二进制参数
4012	今天我们已经聊了很多啦，明天再来找我聊天吧。
4013	这一小时的对话次数已经超过我的极限啦，让我休息一下，待会再聊
4014	这一分钟里我们已经聊了很多啦，休息，休息一下吧
4015	二进制参数错误，请确定binarysId是否对应
4016	单次交互时间过长，请查看文档！
4017	二进制参数错误，有重复binarysId！
4018	二进制参数输入状态异常
4019	二进制参数处理时间超时/第三方引擎参数错误
4022	二进制传输内容过大！
4023	单次交互同类型的二进制参数只允许输入一个
4025	上传数据失败，请稍后~
4026	nlp/tts请求内容过长
4027	请求类型不能为空
4030	robot NLP调用次数耗尽
4031	uri不支持
4032	请求时间戳偏与服务器时间偏差太大，message为服务器时间戳
4100	服务正在升级请稍后再试
4101	请求没有正确初始化！
4102	长时间未请求业务,关闭连接
4200	robot信息异常
4201	nlp/tts处理异常

注意 * 4XXX~5XXX异常，服务端将主动关闭与客户端的connection，其余code不会关闭；