文本审核接口的能力边界与适用场景：参数、响应与错误处理
适用场景与能力概述
内容审核是 UGC 产品上线前必须考虑的一环。凡是允许用户输入文本的地方——评论、弹幕、昵称、签名、私信、文章标题——都可能出现违规内容。人工审核维护复杂度高，纯关键词过滤容易误伤，因此很多团队会引入文本审核 API 做第一道自动筛选。
本次要讨论的文本审核接口（slug:text-censor）提供的是同步单次审核能力。调用方提交一段文本，接口返回一个三态结论：合规、不合规或疑似需人工复核，同时给出命中的违规词、类别和具体说明。它适合放在发布前拦截，也适合作为异步复审的辅助判断依据。
接口地址为https://v1.apizero.cn/api/text-censor，请求方法为POST，按文档说明单账号 QPS 为 5 次/秒。这意味着在接入时需要考虑限流对业务吞吐量的影响，不能把每次按键事件都直接打到这个接口上。
接口能力边界
要正确使用这个接口，需要先明确它“能做什么”和“不能做什么”。文档中明确提到，该接口支持对5000 字以内的文本进行单次请求审核，中英文均按 1 字符计。如果业务文本可能超过这个长度，需要在上游做截断或分片，但分片可能导致跨片语义丢失，因此更稳妥的方式是提前限制用户输入长度。
审核维度覆盖政治敏感、谩骂、色情、违规广告、暴恐、低俗等类别。注意，它返回的是命中违规词的详情，而不是一段“为什么违规”的完整推理。对于语义上隐含但在词表里没有命中的内容，接口可能判为合规，这属于关键词引擎的固有边界。
另一个边界是结论的语义。接口返回is_compliant、is_suspected两个布尔字段。当is_compliant=false时，表示存在明确违规；当is_suspected=true时，表示存在疑似内容，需要人工复核。两者不是互斥关系，都需要结合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 对象，核心字段如下：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
text | string | 是 | 待审核文本，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。
响应结果解读
顶层字段
| 字段 | 类型 | 说明 |
|---|---|---|
code | number | 业务状态码，0表示成功 |
msg | string | 状态说明 |
request_id | string | 请求唯一标识，便于排查问题 |
data | object | 审核结果主体 |
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_suspected=true时，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_suspected=true→ 进入人工审核池。
这些策略应该在业务层实现，而不是期望通过改参数让接口替你决策。
5. 文本预处理
在调用前建议做以下标准化：
- 去掉首尾空白字符。
- 将全角字符统一为半角（如果业务上允许）。
- 对超长文本提前截断，避免 5000 字限制导致请求失败。
注意，截断可能破坏敏感词组合，因此如果截断后仍有审核需求，可以考虑只保留“中间部分”或“首尾各 2500 字”等策略，但这不是接口能力，需要业务方权衡。
6. 降级方案
依赖第三方审核接口时，必须考虑接口不可用的降级。常见做法是：
- 本地维护一份敏感词表做快速拦截。
- 当 API 连续多次超时或返回 5xx 时，将审核任务转人工或延迟重试。
- 对写入操作采用“先入库后异步审核”与“先审核后入库”两种模式中的一种，根据业务风险容忍度选择。
参考文档
- 文档页：https://apizero.cn/aidocs/text-censor
- 原始文档：https://apizero.cn/aidocs/text-censor/raw.md