数美智能文本识别产品API接口文档#

请求参数#

请求URL：#

集群	URL	支持产品列表
北京	`http://api-text-bj.fengkongcloud.com/text/v4`	中文文本
上海	`http://api-text-sh.fengkongcloud.com/text/v4`	中文文本
美国（弗吉尼亚）	`http://api-text-fjny.fengkongcloud.com/text/v4`	中文文本国际化文本
新加坡	`http://api-text-xjp.fengkongcloud.com/text/v4`	中文文本国际化文本

字符编码格式：#

UTF-8字符集编码

请求方法：#

POST

建议超时时长：#

请求参数：#

放在HTTP Body中，采用Json格式，具体参数如下：

请求参数名	类型	参数说明	是否必传	规范
accessKey	string	接口认证密钥	Y	由数美提供
appId	string	应用标识	Y	用于区分应用，需要联系数美服务开通，请使用数美单独提供的传值为准
eventId	string	事件标识	Y	需要联系数美服务开通，请使用数美单独提供的传值为准
type	string	检测的风险类型	Y	可选值： `POLITY`：涉政检测 `VIOLENT`：暴恐检测 `BAN`：违禁检测 `EROTIC`：色情检测 `DIRTY`：辱骂检测 `ADVERT`：广告检测 `PRIVACY`：隐私检测 `ADLAW`：广告法检测 `MEANINGLESS`：无意义检测 `TEXTRISK`：常规风险检测（包含：涉政、暴恐、违禁、色情、辱骂、广告、隐私、广告法、无意义） `FRUAD`：网络诈骗检测 `UNPOACH`：高价值用户防挖检测 `TEXTMINOR`：未成年人内容检测以上type可以下划线组合，如：`TEXTRISK_FRUAD` type间组合取并集，如：`TEXTRISK_POLITY`按照常规风险检测处理
data	json_object	请求的数据内容	Y	最长1MB，详见data参数
kbType	string	知识库类型	N	知识库最大支持510个字符长度的输入，超出后本次请求文本内容无法匹配知识库。如需开通使用请联系数美商务可选值： `PKB`：启用涉政知识库功能
translationTargetLang	string	翻译目标语种	N	将输入的文本翻译成目标语种。如需开通使用请联系数美商务可选值： `zh`：中文 `en`：英文

其中，data的内容如下：

请求参数名	类型	参数说明	是否必传	规范
text	string	需要检测的文本	Y	单次请求字符数上限1万字，超过1万字符时会报错。若传递nickname字段，则会同时校验文本+昵称内容。
relateText	string	需要检测的关联文本	N	文本字数上限128字，超过128字只截取前128字进行识别。传入此字段会结合text一起检测。
tokenId	string	用户账号标识，建议使用贵司用户UID（可加密）自行生成，标识用户唯一身份用作灌水和广告等行为维度风控。如无用户uid的场景建议使用唯一的数据标识传值	Y	由数字、字母、下划线、短杠组成的长度小于等于64位的字符串
lang	string	待检测的文本内容语种	N	可选值和对应语种如下： `zh`：中文 `en`：英文 `ar`：阿拉伯语 `hi`：印地语 `es`：西班牙语 `fr`：法语 `ru`：俄语 `pt`：葡萄牙语 `id`：印尼语 `de`：德语 `ja`：日语 `tr`：土耳其语 `vi`：越南语 `it`：意大利语 `th`：泰语 `tl`：菲律宾语 `ko`：韩语 `ms`：马来语 `auto`：自动识别语种类型默认值zh，国内集群客户可不传或zh；海外文本内容如果不能区分语种建议取值auto，系统会自动检测语种类型
nickname	string	用户昵称	N	校验昵称内容风险，长度限制150字符，超出部分会被截断
ip	string	ip地址	N	发送该文本的的用户公网ipv4或ipv6地址
deviceId	string	数美设备标识	N	数美设备指纹生成的设备唯一标识
extra	json_object	辅助参数	N	用于辅助文本检测的相关信息，详见extra参数
dataId	string	数据标识	N	数据标识

data 中 extra数组每个元素的内容如下：

请求参数名	类型	参数说明	是否必传	规范
receiveTokenId	string	私聊场景下消息接收者的tokenId	N	由数字、字母、下划线、短杠组成的长度小于等于64位的字符串，eventId值为`message`时必传
topic	string	可为话题编号、书评区编号、论坛帖子编号	N	传入的是帖子等数据（eventId值为article）时，开启上下文识别功能，建议传入，否则不能关联上下文
atId	string	群聊场景下被@用户的tokenId	N	由数字、字母、下划线、短杠组成的长度小于等于64位的字符串，eventId值为`groupChat`必传
room	string	直播间/游戏房间编号	N	传入的是直播间、聊天室等数据（eventId值为groupChat）时，开启上下文识别功能，建议传入，否则不能关联上下文
sex	int	性别	N	用于用户性别，可选值： `0`：男性 `1`：女性 `2`：性别不明
passThrough	Json	透传字段	N	该字段内容会随着返回值一起返回

返回结果#

放在HTTP Body中，采用Json格式，具体参数如下：

参数名称	类型	参数说明	是否必返	规范
code	int	返回码	Y	`1100`：成功 `1901`：QPS超限 `1902`：参数不合法 `1903`：服务失败 `1905`：字数超限 `9101`：无权限操作
message	string	返回码描述	Y	和code对应：成功 QPS超限参数不合法服务失败字数超限无权限操作
requestId	string	请求标识	Y	本次请求数据的唯一标识，用于问题排查和效果优化，强烈建议保存
riskLevel	string	处置建议	Y	可能返回值： `PASS`：正常，建议直接放行 `REVIEW`：可疑，建议人工审核 `REJECT`：违规，建议直接拦截
riskLabel1	string	一级风险标签	Y	一级风险标签，当riskLevel为`PASS`时返回`normal`
riskLabel2	string	二级风险标签	Y	二级风险标签，当riskLevel为`PASS`时为空
riskLabel3	string	三级风险标签	Y	三级风险标签，当riskLevel为`PASS`时为空
riskDescription	string	风险原因	Y	当riskLevel为`PASS`时为"正常"
riskDetail	json_object	风险详情	Y	风险详情，详见riskDetail参数
tokenLabels	json object	辅助信息	Y	账号风险画像标签信息见下面详情内容。详见tokenLabels参数
auxInfo	json_object	辅助信息	Y	详见auxInfo参数
allLabels	json_array	辅助信息	Y	命中的所有风险标签以及详情信息。详见allLabels参数
businessLabels	json_array	辅助信息	Y	命中的所有业务标签以及详细信息。详见businessLabels参数
tokenProfileLabels	json_array	辅助信息	N	属性账号类标签。详见账号标签参数
tokenRiskLabels	json_array	辅助信息	N	风险账号类标签。详见账号标签参数
langResult	json_object	语种信息	N	语种信息。详见语种信息参数
kbDetail	json_object	知识库详情	N	知识库详情，详见kbDetail参数
finalResult	int	是否最终结果	Y	值为1，贵司可直接拿返回结果进行处置、分发等下游场景的使用值为0，说明该结果为数美风控的过程结果，还需要经过数美人审再次check后回传贵司
resultType	int	当前结果是机审还是人审环节结果	Y	0：机审，1：人审
disposal	json_object	处置和映射结果	N	数美可按照贵司的标签体系和标识进行返回；未配置自定义标签体系则不返回该字段

其中，disposal结构如下：

返回结果参数名	参数类型	参数说明	是否必返	规范
riskLevel	string	处置建议	是	若贵司有自己的处置规则，数美可按照贵司的处置逻辑配置并返回对应的处置建议；若规则标签未映射上，则返回默认处置建议
riskLabel1	string	映射后一级风险标签	Y	一级风险标签，当数美标签未映射上自定义标签，且disposal下的riskLevel为PASS时，riskLabel1值为normal
riskLabel2	string	映射后二级风险标签	Y	二级风险标签，当数美标签未映射上自定义标签，且disposal下的riskLevel为PASS时，riskLabel2值为空
riskLabel3	string	映射后三级风险标签	Y	三级风险标签，当数美标签未映射上自定义标签，且disposal下的riskLevel为PASS时，riskLabel3值为空
riskDescription	string	映射后风险原因	Y	当riskLevel为PASS时为"正常"
riskDetail	json_object	映射后风险详情	Y	详见riskDetail参数

其中，语种信息langResult结构如下：

参数名称	类型	参数说明	是否必返	规范
detectedLang	string	语种识别结果	N	当在国际化文本产品下传入lang的值为auto时返回该字段。值为标准语言代码表，例如："zh"、"en"、"ar"等
translatedText	string	文本翻译结果	N	当传入translationTargetLang时返回的字段。值为翻译后的文本。

其中auxInfo字段如下：

参数名称	类型	参数说明	是否必返	规范
filteredText	string	辅助信息	N	风险片段被替换为*后的文本
passThrough	json_object	透传字段	否	该字段内容与请求参数data中extra的passThrough的值相同。
contactResult	json_array	辅助信息	N	联系方式识别结果，包含识别出的微信、QQ、手机号的字符串类型和内容。详见contactResult参数
contextText	string	辅助信息	N	上下文生效时返回。
unauthorizedType	string	辅助信息	N	未授权的type。

auxInfo中，contactResult数组每个元素的内容如下：

参数名称	类型	参数说明	是否必返	规范
contactType	int	辅助信息	N	联系方式类型，可选值区间【0-3】，详情如下： `0`：手机号 `1`：QQ号 `2`：微信号
contactString	string	辅助信息	N	联系方式串

其中，riskDetail的内容如下：

参数名称	类型	参数说明	是否必返	规范
matchedLists	json_array	辅助信息	N	命中的客户自定义名单列表。详见matchedLists参数
riskSegments	json_array	辅助信息，高风险内容片段检测文本包含涉政、暴恐、违禁、广告法等风险内容的时候存在	N	详见riskSegments参数

riskDetail中，matchedLists数组每个元素的内容如下：

参数名称	类型	参数说明	是否必返	规范
name	string	辅助信息	N	命中的名单名称
words	json_array	辅助信息	N	命中的敏感词数组。详见words参数

matchedLists中，words数组每个元素的内容如下：

参数名称	类型	参数说明	是否必返	规范
word	string	辅助信息	N	命中的敏感词
position	int_array	辅助信息	N	敏感词所在位置

riskDetail中，riskSegments的内容如下：

参数名称	类型	参数说明	是否必返	规范
segment	string	辅助信息	N	高风险内容片段
position	int_array	辅助信息	N	高风险内容片段所在位置

其中，tokenLabels的详情内容：

参数名称	类型	参数说明	是否必返	规范
UGC_account_risk	json_object	辅助信息	N	UGC内容相关风险。详见UGC_account_risk参数

tokenLabels中，UGC_account_risk的详情内容如下：

参数名称	类型	参数说明	是否必返	规范
sexy_risk_tokenid	float	辅助信息	N	色情账号风险分取值区间[0-1]

其中，allLabels的内容如下：

参数名称	类型	参数说明	是否必返	规范
riskLabel1	string	allLabels不为空时必返	Y	一级风险标签
riskLabel2	string	allLabels不为空时必返	Y	二级风险标签
riskLabel3	string	allLabels不为空时必返	Y	三级风险标签
riskDescription	string	allLabels不为空时必返	Y	风险原因
probability	float	置信度	Y	可选值在0～1之间，值越大，可信度越高注意：allLabels不为空时必返
riskDetail	json_object	风险详情	Y	格式与上层riskDetail结构相同注意：allLabels不为空时必返
riskLevel	string	风险等级	Y	可能返回值： `REVIEW`：可疑 `REJECT`：违规

其中，businessLabels的内容如下：

参数名称	类型	参数说明	是否必返	规范
businessLabel1	string	businessLabels不为空必返	Y	一级业务标签
businessLabel2	string	businessLabels不为空必返	Y	二级业务标签
businessLabel3	string	businessLabels不为空必返	Y	三级业务标签
businessDescription	string	businessLabels不为空必返	Y	标签描述
probability	float	businessLabels不为空必返可选值在0～1之间，值越大，可信度越高	Y	置信度
businessDetail	Json_object	businessLabels不为空必返	Y	业务详情

其中，tokenProfileLabels、tokenRiskLabels的内容如下：

参数名称	类型	参数说明	是否必返	规范
label1	string	一级标签	否
label2	string	二级标签	否
label3	string	三级标签	否
description	string	标签描述	否
timestamp	Int	打标签时间戳	否	13位Unix时间戳，单位：毫秒

其中，kbDetail字段内容如下：

参数名称	类型	参数说明	是否必返	规范
qlabel	string	问题标签	Y	可选值： `UNKNOWN`：没有匹配 `CANNOT_ASK`：问题本身不可提问/不可输入 `EXACTNESS`：问题答案必须正确。包括立场正确 `POSITIVE`：问题答案需要包含正向引导
answer	string	建议答案	Y	当qlabel为"EXACTNESS"或者"POSITIVE"时，会给出数美建议的符合要求的答案。

当lang字段取值zh，或取值auto被识别为中文时，一级标签的内容如下：

一级标签	一级标识	类型	备注
涉政	politics	监管标签	type值为TEXTRISK
暴恐	violence	监管标签	type值为TEXTRISK
色情	porn	监管标签	type值为TEXTRISK
违禁	ban	监管标签	type值为TEXTRISK
辱骂	abuse	监管标签	type值为TEXTRISK
广告法	ad_law	监管标签	type值为TEXTRISK
广告	ad	监管标签	type值为TEXTRISK
黑名单	blacklist	监管标签	type值为TEXTRISK
无意义	meaningless	监管标签	type值为TEXTRISK
隐私	privacy	监管标签	type值为TEXTRISK
网络诈骗	fraud	监管标签	type值为FRUAD
未成年人	minor	监管标签	type值为TEXTMINOR

当为非中文时，一级标签的内容如下：

一级标签	一级标识	类型	备注
涉政	Politics	监管标签	type值为TEXTRISK
暴恐	Violence	监管标签	type值为TEXTRISK
色情	Erotic	监管标签	type值为TEXTRISK
违禁	Prohibit	监管标签	type值为TEXTRISK
辱骂	Abuse	监管标签	type值为TEXTRISK
广告	Ads	监管标签	type值为TEXTRISK
黑名单	Blacklist	监管标签	type值为TEXTRISK

示例#

请求示例#

{
  "accessKey": "*************",
  "appId": "default",
  "eventId": "text",
  "type": "TEXTRISK",
  "data": {
    "text": "加个好友吧 qq12345",
    "tokenId": "4567898765jhgfdsa",
    "ip": "118.89.214.89",
    "deviceId": "*************",
    "nickname": "***********",
    "extra": {
      "topic": "12345",
      "atId": "username1",
      "room": "ceshi123",
      "receiveTokenId": "username2"
    }
  }
}

返回示例#

{
  "allLabels": [
    {
      "probability": 1,
      "riskDescription": "涉政:涉政:涉政",
      "riskDetail": {},
      "riskLabel1": "politics",
      "riskLabel2": "shezheng",
      "riskLabel3": "shezheng",
      "riskLevel": "REVIEW"
    },
    {
      "probability": 0.95559550232975,
      "riskDescription": "广告:加好友:加好友",
      "riskDetail": {
        "matchedLists": [
          {
            "name": "社区敏感词名单",
            "words": [
              {
                "position": [
                  6,
                  7
                ],
                "word": "qq"
              }
            ]
          }
        ]
      },
      "riskLabel1": "ad",
      "riskLabel2": "jiahaoyou",
      "riskLabel3": "jiahaoyou",
      "riskLevel": "REJECT"
    },
    {
      "probability": 1,
      "riskDescription": "广告:联系方式:联系方式",
      "riskDetail": {},
      "riskLabel1": "ad",
      "riskLabel2": "lianxifangshi",
      "riskLabel3": "lianxifangshi",
      "riskLevel": "REJECT"
    }
  ],
  "auxInfo": {
    "contactResult": [
      {
        "contactString": "qq12345",
        "contactType": 2
      }
    ],
    "filteredText": "加个好友吧 **12345"
  },
  "businessLabels": [],
  "code": 1100,
  "message": "成功",
  "finalResult": 1,
  "resultType": 0,
  "requestId": "bb917ec5fa11fd02d226fb384968feb1",
  "riskDescription": "广告:联系方式:联系方式",
  "riskDetail": {},
  "riskLabel1": "ad",
  "riskLabel2": "lianxifangshi",
  "riskLabel3": "lianxifangshi",
  "riskLevel": "REJECT"
}