Skip to main content
Version: v3

文本检测开发指南

info

目前需要联系运营团队申请开通文本检测功能。 申请方式详见开启文本检测服务

介绍​

文本检测为昵称、聊天、个性签名等场景，提供实时、智能、个性化的风险文本检测服务。 基于 AI 及多重识别策略，及时、准确、高效地抵御政治、暴恐、色情、辱骂等违规内容风险。

API 列表​

国内域名：https://whisper.cn.tapapis.com

海外域名：https://whisper-sg.intl.tapapis.com

API 路径介绍
/v2/text/check文本智能识别检测 API，提供准确的判定和类型识别结果

API 协议​

API 以 HTTP 协议对外提供，对于 POST 和 PUT 请求，请求主体必须是 JSON 格式，并且 HTTP Header 的 Content-Type 需要设置为 application/json

API 鉴权​

API 鉴权通过 HTTP Header 设置键值参数进行授权，参数列表如下：

KeyValue描述
X-Client-ID${client_id}国内为 TDS 客户标识（开发者中心 Client ID），海外需平台研发侧提供
X-Server-Secret${server_secret}国内为 TDS 服务密钥（开发者中心 Server Secret），海外需平台研发侧提供

API 详细说明​

接口描述​

提供场景进行区分识别检测效果，可利用多个词库组合，配置多种智能算法进行识别检测。API 会根据聚合后的结果返回一个准确的检测结果，分别是以下三种状态，用户可以根据响应的结果进行过滤：

  • 通过：表示文本内容是健康的，允许放行的，可供记录的内容。
  • 不通过：表示文本内容存在非法文本，不可对内容放行以及记录。
  • 复核：表示文本内容疑似非法，建议昵称场景按不通过处理，聊天场景按通过处理

提示：单次请求数据不得超过 5 MB 大小，文本长度超过 1 万字将会进行截断处理

请求方式​

POST https://{{domain}}/v2/text/check

请求参数​

基本参数​

参数类型必须最大长度说明示例值
scenestring是32业务场景，通过配置不同场景实现多种识别检测规则。请前往过滤场景中获取c1hh9bttqehouf41di00
dataobject是-文本数据提供进行内容识别检测文本信息参数
optobject否-检测可选项，助力一些业务方需求检测选项参数

文本信息参数​

参数类型必须最大长度说明示例值
data_idstring是128数据唯一标识6pYJGpgcPz2ugv
textstring是4096进行检测的文本内容文本检测助力游戏厂商识别违规非法政治内容
user_idstring是128用户 ID，区分用户昵称、宠物昵称、聊天等具体场景nickname:123456
ipstring否128用户请求合法 IP，非必填但需要推送223.161.60.210
publish_timeint64否13内容创建时间戳（毫秒），默认当前请求时间1717140728000
nicknamestring否128用户昵称，辅助校验和数据查询用途小明
server_codestring否128服务器编码，辅助校验prod_cn
group_idstring否32公聊：频道聊天，辅助校验A10
room_idstring否32组团：组队、公会、旅团聊天，辅助校验1U56O47
receive_uidstring否64私聊：一对一聊天，接受玩家 UID，辅助校验132447454
register_timeint64否13用户注册时间戳（毫秒），辅助校验1685518328000
levelint否4角色等级，辅助校验2

检测选项参数​

参数类型必须最大长度说明示例值
replacementstring否1对命中关键词进行替换的符号，默认值"*"*

响应结果​

检测结果数据结构​

参数类型必须说明示例值
request_idstring是请求唯一标识，后续可用于查询数据c1i1955tqehouf41di20
resultint是返回检测结果
0: 通过
1: 拒绝
2: 复核		1
typestring是返回识别类型：
健康： Health
广告：Adv
政治：Politics
辱骂：Abuse
犯罪：Crime
邪教：Heresy
恐怖主义：Terrorism
色情：Porn
赌博：Gamble
违禁品：Contraband
突发敏感事件：SensitiveEvent
违规网站：IllegalWebsite
Politics
filtered_textstring否通过命中关键词返回过滤后的文本内容(text)小明你好*，*就要多读书
hintobject是检测线索线索数据结构

提示：filtered_text 字段可能为空串，响应结果为拒绝且 filtered_text 为空代表该内容需要屏蔽。

线索数据结构​

参数类型必须说明示例值
hit_wordsarray[object]是命中的关键词命中词数据结构

命中词数据结构​

参数类型必须说明示例值
wordstring是关键词xxx
typestring是识别类型（同上）Adv
positionsobject是关键词位置信息关键词位置结构

关键词位置结构​

参数类型必须说明示例值
start_indexint64是起始下标（从 0 开始）0
end_indexint64是结束下标3

请求示例​

curl --location --request POST 'https://whisper.cn.tapapis.com/v2/text/check' \
--header 'Content-Type: application/json' \
--header 'X-Client-ID: *' \
--header 'X-Server-Secret: *' \
--data-raw '{
  "data": {
    "data_id": "49a12d8d-7dc1-41cb-968f-31ddbd2ab3f2",
    "text": "你好，欢迎使用文本检测",
    "ip": "223.161.60.210",
    "user_id": "f2e9172e5172",
    "nickname": "小明"
  },
  "scene": "c1eqbi0e3piuseb840fg",
  "opt": {
    "replacement": "*"
  }
}'

响应示例​

拒绝情况示例

{
    "result": 1,
    "type": "Politics",
    "request_id": "c1i1955tqehouf41di20",
    "filtered_text": "小明你好*，*就要多读书",
    "hint": {
        "hit_words": [
            {
                "word": "xxx",
                "type": "Adv",
                "positions": {
                    "start_index": 4,
                    "end_index": 7
                }
            },
            {
                "word": "ooo",
                "type": "Politics",
                "positions": {
                    "start_index": 8,
                    "end_index": 11
                }
            }
        ]
    }
}

健康情况示例

{
    "result": 0,
    "type": "Health",
    "request_id": "c1i1asltqehouf41di2g",
    "filtered_text": "",
    "hint": {
        "hit_words": []
    }
}

API 错误响应​

当 HTTP 返回码不等于 200 时，即遇到了错误情况将返回以下信息。

参数名称类型必须描述
codeint是接口错误码，返回码见 (https://developers.google.com/maps-booking/reference/grpc-api/status_codes)
messagestring是错误消息
detailsobject否详情信息，具体结构根据不同 code 表示
// 响应 body 为 json 格式
{
    "code": 5, 
    "message": "Text checker is not exists for 'c1exxxxe3pi1useb840fg' scene",
    "details": []
}