内容审核API参数逐项解析与工程化最佳实践

适用场景

在UGC平台、即时通讯、评论系统或信息发布等业务中，文本内容的安全审核是刚需。内容审核API主要用于识别并拦截包含色情、政治违禁、广告、联系方式泄露、谩骂侮辱等敏感内容的文本。典型场景包括：

• 用户发言实时过滤（如弹幕、聊天室）
• 文章/视频标题、描述发布前预审
• 存量数据批量清洗（如历史评论复审）
• 自定义内容合规检查（如品牌词保护）

接口能力边界

基于“敏感词库 + 正则规则 + AI特征评分”三重策略，该API能识别谐音、拼音、符号替换等变体绕过写法。单次请求最长支持5000字（仅action=moderate），批量模式最多50条文本。QPS上限10次/秒，适合中小流量业务；若需要更高吞吐量，建议客户端自行限速或与平台协商。

接口不承诺自动更新词库频率，但会持续优化；也不保证覆盖所有变体（例如极罕见的生僻词或高度个性化的暗语）。建议结合实际业务反馈（误报/漏报）建立自有的补充敏感词列表，作为二次过滤的兜底。

鉴权方式

请求头需要携带API密钥：

• 字段名：X-API-Key
• 类型：string
• 说明：在API管理台获取，注意保密，不要在客户端代码中硬编码。

（素材中的Authorization字段提及但未给出具体使用方式，以文档为准建议使用X-API-Key即可。）

请求参数详解

请求体为JSON对象，结构如下：

{ "action": "moderate", "text": "待审核文本", "texts": [], "mask": false }

action（操作类型）

• 类型：string
• 是否必填：否（默认moderate）
• 可选值：moderate|batch|categories

最佳实践：

• 若单条审核，直接使用moderate；若需要同时审核多条无关文本（如批量导入），用batch可节省网络开销。
• categories返回一个类别列表（如["色情", "政治", "广告", "联系方式", "谩骂", ""]），可用于前端按需展示分类标签，但注意类别名称可能随版本更新，不应硬编码。

text（待审核文本）

• 类型：string
• 是否必填：当action为moderate时必填
• 限制：1 ~ 5000字符（含空格和标点）
• 编码：UTF-8

最佳实践：

• 传入前做基本的非空校验，空字符串会被拒绝（可结合业务定义最短长度）。
• 超过5000字符时，建议截断或分段调用。截断时注意不要在句子中间断开，以免误判。
• 文本中不要包含多余的不可见字符（如零宽空格），否则可能影响敏感词匹配。

texts（批量文本）

• 类型：array[string]
• 是否必填：当action为batch时必填
• 限制：数组长度1~50，每条文本长度1~5000字符

最佳实践：

• 批量模式下，响应中的details数组顺序与输入保持一致，但msgs可能分别返回每条的结果（需解析data.details中的index字段——实际素材示例中未显式返回index，建议以文档为准；通常可以通过顺序对应）。
• 建议将批量大小控制在20条以内，避免因为单条超长造成整体超时（网络超时设置通常3~5秒）。

mask（是否脱敏）

• 类型：boolean
• 是否必填：否（默认false）
• 作用：若为true，响应中会返回masked_text字段，将敏感词替换为*（替换长度与敏感词等长）。

最佳实践：

• 在需要保留原文显示但又不能暴露敏感词的场景非常有用（如用户反馈列表显示脱敏后的内容）。
• 脱敏替换仅覆盖API命中词库/规则的部分，不能保证覆盖所有变体。若业务需要更彻底的过滤，建议结合本地正则再做一次。
• 注意：masked_text只对moderate和batch模式有效；categories模式无此字段。

curl 请求示例

以下示例展示如何审核一条文本并同时获取脱敏结果：

# 将 YOUR_API_KEY 替换为实际密钥 export API_KEY="YOUR_API_KEY" export BASE_URL="https://v1.apizero.cn/api/content-moderation" curl -sS -X POST \ -H "X-API-Key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action": "moderate", "text": "今天天气不错，但那个傻逼经理又找茬了", "mask": true }' \ "$BASE_URL"

执行后收到响应示例（简化）：

{ "code": 0, "data": { "categories": ["谩骂"], "details": [ { "category": "谩骂", "count": 1, "matches": ["傻逼"], "method": "敏感词" } ], "is_pass": false, "masked_text": "今天天气不错，但那个**经理又找茬了", "original_length": 18, "risk_level": "high" }, "msg": "成功", "request_id": "req_xxxx" }

响应字段解析

关于risk_level的使用建议：

• safe：完全通过，可直接展示。
• low：疑似轻微问题（如少量广告信息），可结合人工二次审核或仅降权处理。
• medium：中等风险（如包含电话或邮箱），建议拦截或需人工确认。
• high：高风险（如色情、政治敏感），必须拒绝展示。

注意：risk_level与is_pass并非完全等同——is_pass=false时risk_level通常为medium或high，但极端情况下is_pass=true也可能伴随low级别（如只命中宽松规则）。建议以risk_level为主要决策依据。

常见错误码及处理

使用request_id向平台反馈问题时可以附带该ID。

工程化最佳实践

1. 合理选择mode

• 实时单条审核用moderate，批量导入用batch。不要为了偷懒将单条文本包装成数组使用batch，因为batch的响应结构略有不同，且存在50条限制。

2. 脱敏策略

• 在不存储用户原始敏感词的前提下，mask=true可以直接在前端显示脱敏文本。但注意脱敏仅覆盖API识别的词，第三方自定义词库需自行实现替换。
• 对于需要完整审查日志的场景，建议同时存储原始文本和masked_text，避免审查后无法还原。

3. 降级与兜底

• 当API超时或返回500时，业务不应阻塞用户操作。建议设置超时时间（如2秒），超时后走本地轻量过滤或直接放行并打标记（后续人工复审）。
• 可以定期调用categories接口获取最新类别列表，与本地黑名单同步。

4. 性能考量

• QPS限制10/s，客户端需做限流（如使用令牌桶或滑动窗口）。如果业务峰值超过此值，可在应用层增加队列，批量发送。
• 每条文本平均处理时间约200-500ms（受字数影响），计时应考虑在内。

5. 测试与灰度

• 上线前构造包含敏感词的测测试例（谐音、拼音、全角半角混合），确保API能正确识别。
• 使用risk_level作为阶梯式拦截，可先在high级别做拦截，逐渐下放至medium，观察误报率。

参考文档

• 官方文档页：https://apizero.cn/aidocs/content-moderation
• 原始文档（含更多示例）：https://apizero.cn/aidocs/content-moderation/raw.md

（本文基于公开接口文档撰写，所有参数说明以实际返回为准。）