文本审核接口接入实录：参数细节、返回字段与工程落地

为什么会用到文本审核接口在社区、评论、弹幕等 UGC 场景中运营团队每天要面对大量用户输入。靠人工一条条过目维护复杂度高、响应慢还容易漏。更现实的问题是漏掉一条不合规内容可能带来的内容风险远超一次接口调用本身的代价。文本审核接口解决的正是这个矛盾——在用户提交内容的同时异步或同步地调用一次审核用程序判断文本是否包含敏感信息再决定放行、拦截还是转人工。接口能力边界在接入之前有几个边界条件需要先对齐维度说明请求方式POST请求地址https://v1.apizero.cn/api/text-censor单次文本长度1-5000 个字符中英文均按 1 字符计QPS 限制5 / s结论模式三态合规 / 不合规 / 疑似命中明细每条违规包含 category、word、level、msg衍生字段violations、violation_categories、violation_count值得注意的一点5000 字符的限制是按字符数算的不是按 token 或字节数。中文文本 5000 字、英文文本 5000 个字母都在允许范围内。超过这个长度请求会被拒绝。鉴权方式接口支持两种调用方式匿名调用不带鉴权头适合本地调试和低频测试。API Key 鉴权请求头携带Authorization格式为Bearer sk_live_xxx。-H Authorization: Bearer sk_live_xxxxxxxxxxxxxx另外Content-Type支持application/x-www-form-urlencoded和application/json两种。日常开发建议统一使用 JSON 格式结构清晰嵌套字段也更容易表达。请求参数请求体是一个 JSON 对象核心参数只有一个参数类型必填说明textstring是待审核文本1-5000 个字符最简单的请求体{ text: 今天天气不错适合出门散步。 }curl 接入示例下面是一个完整的 curl 调用使用 API Key 鉴权curl -sS \ -X POST \ -H Authorization: Bearer sk_live_xxxxxxxxxxxxxx \ -H Content-Type: application/json \ -d {text: 今天天气不错适合出门散步。} \ https://v1.apizero.cn/api/text-censor如果你是在本地快速验证也可以先去掉 Authorization 头匿名调用一次curl -sS \ -X POST \ -H Content-Type: application/json \ -d {text: 这是一条测试内容} \ https://v1.apizero.cn/api/text-censor注意sk_live_xxx是需要替换成你自己的真实 Key。返回字段逐项拆解以素材中的响应为例逐一说明每个字段的含义。先看顶层结构{ code: 0, msg: 成功, request_id: abc123def456, data: { } }code接口级状态码0表示请求处理成功。msg与 code 对应的描述信息。request_id单次请求的追踪 ID排查问题时可以拿着它去服务端查日志。data审核结果的主体。再看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: [法轮功, 邪教] }审核结论is_compliant和is_suspected组合出三态结论is_compliantis_suspected业务含义truefalse合规直接放行falsefalse不合规拦截并提示falsetrue疑似转人工复核conclusion和conclusion_type是结论的冗余表达方便前端直接展示不需要再自己映射。违规详情details是数组每个元素对应一条违规命中category违规类别如政治、谩骂、色情、广告等。word触发审核的词。level违规等级数值越高越严重。msg该条命中的说明文案。衍生字段violations对所有details.word去重后的数组。violation_categories对details.category去重后的数组。violation_count合规/不合规/疑似 中违规条目总数当前示例中为 2。这些字段的价值在于前端不需要自己遍历details做去重直接展示「触发 2 项违规政治」即可。常见错误与排查思路接入过程中以下几个问题出现频率较高。1. 请求被拒返回 HTTP 4xx优先检查三件事Content-Type是否设置正确。JSON 格式是否合法有没有多余逗号或未转义引号。文本长度是否超过 5000 字符。2. 鉴权失败确认 Key 是否以sk_live_开头。确认请求头是Authorization而不是X-API-Key。素材中的 curl 示例使用的是X-API-Key但 Header 参数表里标明的是Authorization两者并存时以 Header 表为准。3. 返回 code 非 0检查msg字段给出的错误描述。携带request_id反馈给接口提供方协助排查。工程化落地建议缓存 key 不要用原文素材中提到缓存 key 使用 sha256 哈希原文不进入 key。这意味着同一段文本重复审核时可以直接命中缓存避免重复调用。工程上建议这样落import hashlib text 用户提交的原始内容 key hashlib.sha256(text.encode(utf-8)).hexdigest() # 以 key 为缓存的键value 存审核结果注意哈希的是原文但原文本身不要作为 key 的一部分。日志脱敏错误日志里不要记录用户提交的文本内容只记录request_id、text_length这类元信息。如果确实需要回查可以用哈希后的值关联而非原文。超时与重试接口 QPS 上限为 5 / s。如果业务峰值远超这个量级要做两件事本地增加限流避免把压力全部打到接口上。对超时请求设置合理的重试策略建议指数退避重试次数 2-3 次即可。异步审核与消息队列用户发一条评论同步等接口返回再放行体验上可接受。但如果文本量大或者涉及图片、视频等多模态内容建议改成异步用户提交后先进入待审核队列后端消费队列逐条调用审核接口结果出来后回调通知前端。存储与快照审核结果建议和原文一起落库至少保留三个核心字段最终结论合规/不合规/疑似命中的违规类别列表对应的request_id一旦后续出现争议可以拿着request_id追溯审核链路。总结文本审核接口的价值在于把「内容是否合规」这个主观判断变成了一个可编程的客观决策。接入维护复杂度不高——一个 POST 请求、一个文本参数、一段 JSON 响应。但真正要做好需要在意的是边界条件5000 字符、三态结论、工程细节缓存哈希、日志脱敏、限流重试以及前端如何高效利用violations和violation_categories这些衍生字段。建议先用 curl 跑通一次完整请求观察不同输入文本下的返回差异再进到代码层对接。参考文档文档页https://apizero.cn/aidocs/text-censor原始文档https://apizero.cn/aidocs/text-censor/raw.md