内容安全三道防线：内容审核API的多场景接入与响应解读

从业务痛点说起内容审核几乎是每个带有用户生成内容UGC产品的公共话题。社区评论、用户昵称、弹幕、私信、商品评价……任何一处用户可输入文本的地方都有可能被夹带敏感信息。如果完全靠人工审核维护复杂度和时效都难以跟上如果只依赖简单的关键词黑名单又很容易被谐音、拼音、符号插入等变体绕过。本文以一个具体的文本审核API为例展示如何通过一套接口在一个或多个业务场景中落地内容安全能力。API基于敏感词库 正则规则 AI 特征评分三重策略对文本中的色情、政治、广告、联系方式、、谩骂六大类内容进行检测输出 low / medium / high 风险等级并且可以按需返回脱敏后的文本。接口能力边界在接入前先明确这个接口能做什么、不能做什么。这一点对后续的架构设计很重要。支持的操作类型action用途限制moderate单条文本审核文本长度 1-5000 字batch批量文本审核最多 50 条categories查询支持的敏感分类无检测范围色情内容政治敏感内容广告信息联系方式手机号、微信号、QQ 等话术谩骂攻击能力边界接口只处理文本内容不处理图片、音视频限流为 10 QPS超出后需要等待或做客户端限速接口不负责业务层的决策最终是放行、拦截还是转人工需要业务方根据risk_level和is_pass自行决定。请求参数与鉴权鉴权方式接口使用 Header 传递 API Key字段名为Authorization。从 API 事实卡来看该字段在文档中标记为非必需但实际调用时建议务必携带未携带或 Key 无效通常会返回 401 或 403。Authorization: Bearer 你自己的 API Key需要说明的是API 事实卡中未给出具体的鉴权格式细节是否带 Bearer 前缀、Key 从哪里获取这部分以官方文档为准。请求体字段请求体是一个 JSON 对象核心字段如下参数类型必须说明actionstring否操作类型moderate默认/batch/categoriestextstringcondition待审核单条文本仅moderate模式使用1-5000 字textsarraycondition批量文本数组仅batch模式使用最多 50 条maskboolean否是否返回脱敏文本默认false注意text和texts是互斥的取决于action的值。如果actionmoderate但没有传text或actionbatch但没有传texts服务端会按参数校验失败处理。三种操作模式的 curl 示例模式一单条文本审核这是最基本的用法适合审核用户提交的单个字段比如评论内容、个人简介等。curl -sS \ -X POST \ -H Authorization: Bearer $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { action: moderate, text: 今天天气不错晚上一起吃饭吧, mask: true } \ https://v1.apizero.cn/api/content-moderation你需要在执行前先在环境变量中设置APIZERO_API_KEY或直接将字符串替换到 Header 中。模式二批量审核适合内容发布后台的定时巡检、存量数据清洗等场景。curl -sS \ -X POST \ -H Authorization: Bearer $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { action: batch, texts: [第一条待审核内容, 第二天带敏感词的内容], mask: true } \ https://v1.apizero.cn/api/content-moderation模式三查询分类在接入初期建议先调用一次categories模式确认当前接口实际返回的分类集合避免在代码里写死分类名。curl -sS \ -X POST \ -H Authorization: Bearer $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {action: categories} \ https://v1.apizero.cn/api/content-moderationPython 代码接入示例curl 适合调试工程接入更推荐用 Python 等语言封装。以下示例使用requests库实现一次带超时与错误处理的调用。import os import requests def moderate_text(text: str, mask: bool True) - dict: 单条文本审核 api_url https://v1.apizero.cn/api/content-moderation headers { Authorization: fBearer {os.getenv(APIZERO_API_KEY, )}, Content-Type: application/json, } payload { action: moderate, text: text, mask: mask, } try: resp requests.post(api_url, jsonpayload, headersheaders, timeout5) resp.raise_for_status() # 非 2xx 会抛异常 return resp.json() except requests.exceptions.Timeout: # 工程上建议做重试或降级处理 return {code: -1, msg: request timeout} except requests.exceptions.RequestException as exc: return {code: -2, msg: str(exc)} if __name__ __main__: sample 你这个傻逼整天就知道打广告加我微信xxxxx result moderate_text(sample, maskTrue) data result.get(data, {}) print(风险等级:, data.get(risk_level)) print(是否需要拦截:, data.get(is_pass)) print(命中的分类:, data.get(categories)) print(脱敏后文本:, data.get(masked_text))响应字段解读以一个成功的响应为例{ code: 0, data: { categories: [谩骂], details: [ { category: 谩骂, count: 2, matches: [傻逼, 脑残], method: 敏感词 } ], is_pass: false, masked_text: 你这个****吧, original_length: 10, risk_level: high }, msg: 成功, request_id: abc123 }逐项说明字段类型说明codeint业务状态码0表示请求成功msgstring结果描述request_idstring请求追踪 ID排查问题时建议记录下来data.categoriesarray命中的敏感分类列表可能为空数组data.detailsarray每个分类的检测细节data.details[].categorystring分类名data.details[].countint命中次数data.details[].matchesarray命中的具体词或模式data.details[].methodstring命中方式敏感词/正则/AI特征data.is_passboolean是否通过false表示存在风险data.masked_textstring脱敏后的文本仅在masktrue时返回data.original_lengthint原始文本长度data.risk_levelstring综合风险low/medium/highmethod字段值得特别关注。如果检测结果显示正则说明命中了变体规则如谐音、拼音、符号插入如果显示AI特征说明没有匹配到具体词库但 AI 打分认为文本有风险。可以根据生产环境的误判率对不同method的结果采取差异化策略。风险等级与业务策略risk_level和is_pass是两个不同的维度。is_pass是一个简单的布尔值risk_level则提供了更细的粒度。建议的映射策略risk_level建议处理方式low放行medium人工复核队列或限制可见范围high直接拦截或要求用户修改这只是参考具体阈值可以根据业务容忍度调整。如果误判代价高可以把medium也纳入人工审核如果内容量极大可以只对high做拦截。常见错误与排查路径以下是根据 HTTP 状态和返回结构整理的排查思路。API 事实卡没有给出完整的错误码表以下部分为通用经验具体的错误码字段以文档为准。401/403鉴权失败确认AuthorizationHeader 是否携带确认 API Key 是否有效是否过期如果文档要求 Bearer 前缀检查是否拼写正确。400参数错误actionmoderate时text不能为空actionbatch时texts不能是空数组text超过 5000 字会被拒绝texts超过 50 条会被拒绝。429触发限流API 限制为 10 QPS客户端需要做本地限速或请求排队更推荐的做法是批量模式合成一次请求而不是高频调用单条审核。500服务端异常记录request_id便于在联系技术支持时提供对调用方而言需要实现退避重试建议指数退避例如 1s / 2s / 4s / 8s最多重试 3 次。工程化接入注意事项1. 区分同步与异步场景像社区发帖这种场景用户点了发布按钮一般等不了 5 秒。如果接口响应时间长建议改为异步先把内容写入待审表后台任务调审核接口再回写审核结果。如果是私信这种实时性要求高的场景可以对单条做同步调用但要有超时兜底。2. 高可用降级方案任何第三方接口都可能抖动。业务上必须设计降级逻辑审核接口超时或 5xx 时是放行还是拦截建议对高风险内容默认拦截Fail-Closed对普通场景默认放行Fail-Open并记录日志。至少保证核心链路不因为审核服务不可用而整体瘫痪。3. 合理利用批量模式批量接口上限是 50 条适合后台定时任务。例如每天凌晨跑全量存量内容的巡检或者在高峰期把评论攒起来按批提交减少 QPS 压力。4. 缓存与去重敏感词检测结果在一定时间段内是稳定的。对相同内容重复审核是浪费。可以做一个简单的缓存以文本 hash 为 key把低风险结果缓存 5-15 分钟命中缓存直接返回。5. 保留原始文本与审核日志合规审计时需要回溯。建议在数据库里单独保存原始文本、审核结果、风险等级、请求 ID 和检测细节JSON 序列化这些数据对后续分析召回率和误判率非常重要。小结这个内容审核 API 的定位很清晰用三重策略降低变体绕过的风险通过风险等级和脱敏能力让业务侧有灵活的处理空间。接入时重点把握好三点参数语义要理解准确尤其是moderate和batch的互斥关系、风险等级要映射到明确的业务动作、工程上要做好超时和降级。对于内容审核这件事没有哪个接口能做到百分百准确。合理的做法是让 API 承担第一道过滤把明显违规的内容挡掉把模糊的内容交给人工或更精细的策略处理。参考文档API 文档页https://apizero.cn/aidocs/content-moderation原始文档Markdownhttps://apizero.cn/aidocs/content-moderation/raw.md