适用场景与能力概述内容审核是 UGC 产品上线前必须考虑的一环。凡是允许用户输入文本的地方——评论、弹幕、昵称、签名、私信、文章标题——都可能出现违规内容。人工审核维护复杂度高纯关键词过滤容易误伤因此很多团队会引入文本审核 API 做第一道自动筛选。本次要讨论的文本审核接口slug:text-censor提供的是同步单次审核能力。调用方提交一段文本接口返回一个三态结论合规、不合规或疑似需人工复核同时给出命中的违规词、类别和具体说明。它适合放在发布前拦截也适合作为异步复审的辅助判断依据。接口地址为https://v1.apizero.cn/api/text-censor请求方法为POST按文档说明单账号 QPS 为 5 次/秒。这意味着在接入时需要考虑限流对业务吞吐量的影响不能把每次按键事件都直接打到这个接口上。接口能力边界要正确使用这个接口需要先明确它“能做什么”和“不能做什么”。文档中明确提到该接口支持对5000 字以内的文本进行单次请求审核中英文均按 1 字符计。如果业务文本可能超过这个长度需要在上游做截断或分片但分片可能导致跨片语义丢失因此更稳妥的方式是提前限制用户输入长度。审核维度覆盖政治敏感、谩骂、色情、违规广告、暴恐、低俗等类别。注意它返回的是命中违规词的详情而不是一段“为什么违规”的完整推理。对于语义上隐含但在词表里没有命中的内容接口可能判为合规这属于关键词引擎的固有边界。另一个边界是结论的语义。接口返回is_compliant、is_suspected两个布尔字段。当is_compliantfalse时表示存在明确违规当is_suspectedtrue时表示存在疑似内容需要人工复核。两者不是互斥关系都需要结合conclusion字段判断最终状态。鉴权与请求参数Header 参数接口提供两种鉴权方式建议以官方文档为准。Authorization可选类型为string格式为Bearer sk_live_xxx用于 API Key 鉴权。Content-Type可选类型为string支持application/x-www-form-urlencoded或application/json。另外素材中的 curl 示例使用了X-API-Key请求头与上述Authorization形式不同。实际使用时需要确认文档中标注的鉴权头优先级或者两种都支持。稳妥的做法是如果使用 API Key 就只在Authorization或X-API-Key中选一种传递避免冗余或冲突。请求体字段请求体是一个 JSON 对象核心字段如下字段类型必填说明textstring是待审核文本1-5000 个字符中英文均按 1 字符计示例{ text: 今天天气不错适合出门散步。 }这里的text是唯一的业务参数接口没有提供自定义词库、分类开关或阈值调节参数。如果你的业务需要对特定类别做不同处理只能在拿到返回值后自己实现策略。curl 接入示例下面是一个可直接复制的 curl 示例。为了兼容素材中给出的两种鉴权头这里以X-API-Key为例如果使用Authorization替换对应 Header 即可curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {text: 今天天气不错适合出门散步。} \ https://v1.apizero.cn/api/text-censor执行成功后会返回类似下面的 JSON 响应。这里把违规文本“法轮功是邪教组织”作为示例输入便于观察违规命中结构{ code: 0, data: { conclusion: 不合规, conclusion_type: 2, details: [ { category: 政治, level: 3, msg: 存在政治内容不合规, word: 法轮功 }, { category: 政治, level: 3, msg: 存在政治内容不合规, word: 邪教 } ], is_compliant: false, is_suspected: false, text: 法轮功是邪教组织, text_length: 8, violation_categories: [政治], violation_count: 2, violations: [法轮功, 邪教] }, msg: 成功, request_id: abc123def456 }注意上述 curl 中的$APIZERO_API_KEY只是环境变量占位符实际运行前需要替换成你从 API 管理后台获取的真实 Key。响应结果解读顶层字段字段类型说明codenumber业务状态码0表示成功msgstring状态说明request_idstring请求唯一标识便于排查问题dataobject审核结果主体data 对象data对象包含以下字段conclusion字符串比如“合规”“不合规”或“疑似”。这是给人看的文本结论。conclusion_type数字与conclusion对应的类型码建议在代码中使用数字判断而非中文字符串。is_compliant布尔值true表示全部合规。is_suspected布尔值true表示需要人工复核。text回显的原始文本。text_length数字文本实际长度。details数组命中的每条违规词详情包含category违规类别如“政治”。word触发违规的关键词或短语。level等级数字示例中为3具体等级含义需以文档为准。msg说明文字。violations数组去重后的违规词列表。violation_categories数组命中的类别去重结果。violation_count数字违规条数。这几个衍生字段对前端特别友好。例如你可以直接展示“触发 2 项违规政治”无需自己遍历details再统计。三态判断逻辑在实际开发中推荐按以下优先级处理if data[is_suspected]: # 进入人工复核队列 pass elif data[is_compliant]: # 放行 pass else: # 拦截或提示用户修改 pass需要注意的是is_suspectedtrue时is_compliant可能为false也可能为true。不要只用其中一个字段做判断务必同时检查两个字段。常见错误与排查素材没有给出完整的错误码表以下是根据 HTTP 状态和常见 API 设计整理出的排查思路具体错误码以官方文档为准。鉴权失败401 / 403检查请求头中是否带了 API Key。检查 Key 是否有效注意sk_live_前缀不能丢。检查是否同时传了Authorization和X-API-Key导致服务端解析冲突。请求体格式错误400确认Content-Type与实际请求体一致。如果用application/json请求体必须是合法 JSON。确认text字段存在且为字符串。确认文本长度在 1-5000 字符之间。空字符串或超过上限都会报错。限流429文档标注 QPS 为 5 次/秒。如果并发超过该值服务端可能返回限流错误。此时应该在客户端引入信号量或令牌桶控制单机请求速率。对失败请求做指数退避重试而不是固定间隔疯狂重试。将部分非实时审核场景改为消息队列异步消费降低峰值压力。服务端异常5xx工程化注意事项1. 缓存与隐私保护文档提到缓存 key 使用 sha256 哈希原文不进入 key错误日志不记录文本内容。这说明接口在设计上已考虑敏感信息脱敏。但在业务侧仍然不建议将用户原文写入业务日志或第三方监控系统。如果需要留痕只记录text_length和request_id即可。2. 结果结构化存储每次审核结果建议落库时将details展开成独立表或 JSON 字段并保留request_id。这样当用户申诉时可以定位到当时的审核依据。衍生字段violations和violation_categories可以加速查询但原始details不要丢弃。3. 超时设置文本审核属于同步接口实测网络开销因区域而异。建议将 HTTP 客户端超时设置为 5-10 秒连接超时 3 秒。不要设置为无限超时否则容易拖垮线程池。4. 业务策略与接口能力解耦接口只负责“判断是否命中违规”不负责“如何处置”。例如命中“政治”类别 → 直接拦截。命中“低俗”类别 → 强制修改后再提交。is_suspectedtrue→ 进入人工审核池。这些策略应该在业务层实现而不是期望通过改参数让接口替你决策。5. 文本预处理在调用前建议做以下标准化去掉首尾空白字符。将全角字符统一为半角如果业务上允许。对超长文本提前截断避免 5000 字限制导致请求失败。注意截断可能破坏敏感词组合因此如果截断后仍有审核需求可以考虑只保留“中间部分”或“首尾各 2500 字”等策略但这不是接口能力需要业务方权衡。6. 降级方案依赖第三方审核接口时必须考虑接口不可用的降级。常见做法是本地维护一份敏感词表做快速拦截。当 API 连续多次超时或返回 5xx 时将审核任务转人工或延迟重试。对写入操作采用“先入库后异步审核”与“先审核后入库”两种模式中的一种根据业务风险容忍度选择。参考文档文档页https://apizero.cn/aidocs/text-censor原始文档https://apizero.cn/aidocs/text-censor/raw.md