真实业务场景下的内容审核：三重检测机制与API实践
适用场景
随着互联网平台用户生成内容（UGC）爆发式增长，文本内容审核成为必不可少的一环。本API适用于以下典型场景：
- 社交平台的用户发言、评论审核
- 论坛、博客的文章发布前检测
- 聊天室实时消息过滤
- 客服对话中的敏感内容监控
- 其他需要自动化识别色情、政治、广告、联系方式、、谩骂等类别的场景
相较于简单的关键词过滤，该API采用“敏感词库+正则规则+AI特征评分”三重策略，能有效识别谐音、拼音、符号替换等变体绕过。同时支持风险等级划分和可选脱敏输出，方便开发者根据业务需求进行降级或阻断。
接口能力边界
- QPS：10/s（请根据业务量合理控制并发，超限会返回429）
- 单次请求文本长度：1-5000字符（action=moderate时）；批量模式最多50条
- 检测类别：色情、政治、广告、联系方式、、谩骂共6大类
- 结果输出：风险等级（safe/low/medium/high）、命中类别、具体匹配内容、脱敏文本（可选）
- 适用文本语言：中文为主，混合其他语言亦可部分检测（以实际效果为准）
鉴权方式与请求头
该API通过请求头传递API密钥进行身份验证。根据文档，有两种方式（以实际支持为准）：
X-API-Key：curl示例中使用Authorization：可选，但未给出具体格式（建议以文档最新说明为准）
在实际开发中，建议将密钥存储在环境变量或安全配置中，避免硬编码。
请求参数详解
请求体为JSON对象，包含以下字段：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| action | string | 否 | 操作类型：moderate（默认，单文本审核）/ batch（批量审核）/ categories（仅返回分类信息） |
| text | string | 条件必填 | 待审核文本，action=moderate时必填，长度1-5000字符 |
| texts | array | 条件必填 | 批量文本列表，action=batch时必填，最多50条，每条长度不限但建议合理 |
| mask | boolean | 否 | 是否返回脱敏文本，默认false；设为true则在返回的masked_text中用‘*’替换敏感字符 |
注意：action和texts是互斥的，根据action类型填写对应的文本参数。
接入示例（curl）
以下是一个单文本审核并开启脱敏的curl示例：
# 请将 $APIZERO_API_KEY 替换为你的真实密钥 curl -sS -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action": "moderate", "text": "你这个傻逼，脑残吧", "mask": true}' \ "https://v1.apizero.cn/api/content-moderation"响应示例（成功）：
{ "code": 0, "msg": "成功", "request_id": "abc123", "data": { "is_pass": false, "risk_level": "high", "categories": ["谩骂"], "details": [ { "category": "谩骂", "method": "敏感词", "count": 2, "matches": ["傻逼", "脑残"] } ], "original_length": 10, "masked_text": "你这个**，**吧" } }若未开启mask，则返回对象中不包含masked_text字段。
批量审核示例：
curl -sS -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action": "batch", "texts": ["正常文本", "又是一个傻逼"], "mask": false}' \ "https://v1.apizero.cn/api/content-moderation"批量模式下，返回的data是一个数组，每个元素对应一条文本的检测结果，顺序与输入一致。
返回字段解析
响应结构：
- code: 整型，0表示成功，非0表示错误
- msg: 字符串，状态描述
- request_id: 字符串，请求唯一标识，可用于日志追踪
- data: 对象（单审）或数组（批量），包含审核结果
data字段详细说明：
| 字段 | 类型 | 说明 |
|---|---|---|
| is_pass | boolean | 是否通过审核（所有类别均为safe时true） |
| risk_level | string | 风险等级：safe（安全）/ low（低风险）/ medium（中风险）/ high（高风险），根据最严重类别决定 |
| categories | array | 命中的敏感类别列表（如["谩骂", "广告"]） |
| details | array | 每个类别下的详细命中信息 |
| original_length | int | 原始文本长度 |
| masked_text | string | 仅在mask=true时存在，脱敏后的文本 |
details数组中每个元素包含：
- category: 类别
- method: 检测方式（敏感词、正则、AI特征）
- count: 命中次数
- matches: 命中的具体内容列表
常见错误与处理
| HTTP状态码 | 返回code | 说明 | 处理建议 |
|---|---|---|---|
| 200 | 0 | 成功 | 正常处理返回数据 |
| 200 | 非0 | 业务错误 | 根据msg判断，如“文本为空”等 |
| 400 | - | 请求参数错误 | 检查JSON格式、必填字段 |
| 401 | - | 认证失败 | 检查API密钥是否正确 |
| 403 | - | 权限不足 | 确认密钥是否有权限调用该接口 |
| 429 | - | 请求过频 | 降低并发，添加重试机制 |
| 500 | - | 服务端错误 | 重试，若持续可联系技术支持 |
特别注意：当code非0时，data可能不存在或为null，务必判空。
工程化注意事项
- 密钥管理：不要在代码中硬编码API密钥，使用环境变量或密钥管理服务。
- 错误重试：对429和5xx错误实现指数退避重试，避免雪崩。
- 文本长度控制：单条文本不超过5000字符，超长可考虑截断或分段审核。
- 批量模式限制：批量最多50条，如需审核更多文本，分多次请求。
- 脱敏使用：若业务需要展示部分内容，可使用masked_text替换原文本，但注意脱敏后长度可能与原文不同。
- 风险等级策略：根据业务要求对高风险（high）直接拦截，中风险（medium）人工审核，低风险（low）放行但标记，安全（safe）直接通过。
- 并发控制：QPS 10/s，建议使用队列自控，避免触发限流。
- 日志与监控：记录request_id用于问题排查，监控响应时间、错误率等指标。
参考文档
- 官方文档：https://apizero.cn/aidocs/content-moderation
- 原始文档(RAW)：https://apizero.cn/aidocs/content-moderation/raw.md
（注：文档中可能有更多细节，请以最新版本为准。）