从参数到返回值：文本审核接口的能力边界与适用场景

适用场景：哪些业务需要文本审核接口

任何涉及用户生成内容（UGC）的平台，都可能面临违规文本带来的合规风险。典型场景包括：

  • 社区评论：论坛、微博、视频弹幕，实时过滤恶意评论、政治敏感、色情低俗内容。
  • 即时通讯：聊天消息、群公告，防止涉政、违法信息扩散。
  • 产品反馈：售后工单、用户投诉文本，在公开前自动屏蔽攻击性内容。
  • AI对话日志：对LLM生成的回复做二次审核，拦截幻觉产生的违规输出。
  • 内容发布：博客、文章、商品描述，在上线前进行多维度安全检测。

文本审核接口为上述场景提供了一套开箱即用的策略：返回“合规/不合规/疑似”三态结论，附带命中违规词详情，帮助运营人员快速决策或触发人工复审流程。

接口能力边界：知道它能做什么，才知道怎么用

请求容量与性能上限

维度数值说明
单次文本长度1–5000 字符中英文均按1字符计，超过5000字符需截断或分片
QPS5 / s每秒最多5次请求，超限可能返回429或触发降级
并发策略HTTP短连接建议复用连接池，但注意服务端对长连接的支持按实际环境为准

审核维度与三态结论

接口对文本进行多维度扫描，覆盖：政治敏感、谩骂、色情、违规广告、暴恐、低俗等类别。每一条命中违规信息包含：

  • category：违规类别（如政治、色情）
  • word：触发词原文
  • level：严重等级（数值越高越严重）
  • msg：可读的说明文字

返回结论通过三个布尔字段表达：

{ "is_compliant": true, "is_suspected": false, // 若is_compliant为true，则视为合规 }

三态逻辑如下：

is_compliantis_suspected结论推荐处理
truefalse合规放行
falsefalse不合规拒绝/屏蔽
falsetrue疑似人工复审或二次拦截

注意：素材中的响应示例显示“is_compliant: false, is_suspected: false”，说明该示例文本“法轮功是邪教组织”被明确判定为不合规，不需要人工复核。

隐私保护机制

接口在缓存和日志层面做了隐私约束：

  • 缓存key：对原文做SHA256哈希，原文不入key。
  • 错误日志：不记录文本内容，仅记录request_id与错误码。

这意味着即便缓存命中或日志泄漏，攻击者也无法还原原始文本，适合处理敏感用户数据。

请求参数详解：Header与Body

Header鉴权

接口支持两种鉴权方式（二选一或同时提供）：

  1. Authorization（Bearer Token）：

    • 格式：Authorization: Bearer sk_live_xxxxxxxxxxxxxx
    • 非必填，若填写则使用该密钥鉴权；匿名调用（省略）时每日有30次免鉴权限额。

  2. X-API-Key（curl示例中使用）：

    • 格式：X-API-Key: sk_live_xxxxxxxxxxxxxx
    • 与Authorization等效，但实际服务端按一方优先处理，文档未明确定义优先级，建议只使用其中一种。

Content-Type

支持两种：

  • application/json（推荐）
  • application/x-www-form-urlencoded

若使用JSON：请求体为一个包含text字段的对象。

请求Body字段

字段类型必填描述示例
textstring是待审核文本，1-5000字符"今天天气不错，适合出门散步。"

这里没有其他字段，结构极简。

curl示例与代码接入

直接使用curl

以下示例使用X-API-Key头（请将$APIZERO_API_KEY替换为真实的API密钥）：

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"

如果你使用Authorization头，可以写成：

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或X-API-Key头即可，但每天仅30次接口调用。生产环境务必配置密钥。

使用Python（requests库）

import requests import json API_URL = "https://v1.apizero.cn/api/text-censor" API_KEY = "sk_live_xxxxxxxxxxxxxx" # 替换为真实密钥 headers = { "Content-Type": "application/json", "Authorization": f"Bearer {API_KEY}" } data = {"text": "今天天气不错，适合出门散步。"} resp = requests.post(API_URL, headers=headers, json=data) result = resp.json() print(json.dumps(result, indent=2, ensure_ascii=False))

使用Node.js（axios）

const axios = require('axios'); const API_URL = 'https://v1.apizero.cn/api/text-censor'; const API_KEY = 'sk_live_xxxxxxxxxxxxxx'; // 替换 axios.post(API_URL, { text: '今天天气不错，适合出门散步。' }, { headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' } } ).then(response => { console.log(JSON.stringify(response.data, null, 2)); }).catch(err => console.error(err));

返回值解读：字段拆解与前端展示建议

完整的成功响应结构如下（已去除外层数组包裹）：

{ "code": 0, "msg": "成功", "request_id": "abc123def456", "data": { "is_compliant": false, "is_suspected": false, "conclusion": "不合规", "conclusion_type": 2, "text": "法轮功是邪教组织", "text_length": 8, "details": [ { "category": "政治", "level": 3, "msg": "存在政治内容不合规", "word": "法轮功" }, { "category": "政治", "level": 3, "msg": "存在政治内容不合规", "word": "邪教" } ], "violations": ["法轮功", "邪教"], "violation_categories": ["政治"], "violation_count": 2 } }

关键字段说明

字段类型含义
codeint业务状态码，0表示成功；非0参见错误码
request_idstring请求唯一标识，排障时需提供
data.is_compliantbool是否完全合规
data.is_suspectedbool是否疑似违规（需要人工复核）
data.conclusionstring中文结论：合规 / 不合规 / 疑似
data.conclusion_typeint结论数字标识：1合规 / 2不合规 / 3疑似（根据素材示例推断，建议以文档为准）
data.detailsarray命中违规详情列表，每个元素包含category/word/level/msg
data.violationsarray[string]去重后的违规词数组
data.violation_categoriesarray[string]去重后的违规类别数组
data.violation_countint违规条目总数

前端快速展示方案

利用violations、violation_categories、violation_count三个衍生字段，前端无需再遍历details即可展示统计信息，例如：

“触发 2 项违规：政治”

点击详情可展开显示具体词：“法轮功”、“邪教”。

常见错误排查

错误现象可能原因排查思路
响应401API密钥无效或未提供检查密钥前缀是否为sk_live_，确认请求头正确
响应429超出QPS配额（5/s）增加重试退避或降低请求频率
响应413请求体过大检查text字段长度是否超过5000字符
响应400JSON格式错误或缺少必填字段验证请求体是否为合法JSON，text字段是否存在
响应500服务端异常记录request_id，联系技术支持（文档链接见后）
匿名调用提示“rate limit”匿名用户每日30次已用完升级为带密钥调用

工程化注意事项

1. 限流与重试机制

由于QPS上限为5，建议在客户端实现令牌桶或固定窗口限流。使用指数退避重试（例如第一次等待200ms，第二次500ms，第三次1s）应对429。若业务并发需求远超5，应考虑将文本分批发送或与平台协商提升配额（具体规则以官方文档为准）。

2. 请求分片策略

对于超过5000字符的文本，需要手动切分。切分策略应尽量保持语义完整：

  • 优先按段落换行符切分，每段不超过5000字符。
  • 若段落超长，按标点符号（句号、问号）切分。
  • 切分后逐段调用接口，最终合并结果（任一子段不合规则整体判定为不合规）。

3. 缓存与降级

  • 对已审核的文本计算SHA256存入本地缓存（TTL根据业务调整），避免重复请求浪费配额。
  • 若接口不可用，可降级为“疑似”等待人工审核，或使用本地简单规则（如正则屏蔽常见违禁词）作为兜底。

4. 隐私与合规

  • 生产环境务必使用HTTPS，避免明文传输用户文本。
  • 即使接口不记录文本内容，业务方也应遵循自身隐私政策，在调用前告知用户“内容将通过第三方审核服务检查”。

5. 异步处理与回调

若审核非实时必要（如用户发表内容后先发布再异步追查），可采用消息队列将审核任务异步处理，失败时记录日志并触发告警。接口本身为同步设计，不支持callback回调。

参考文档

  • 接口文档页：https://apizero.cn/aidocs/text-censor
  • 原始接口文档（Markdown）：https://apizero.cn/aidocs/text-censor/raw.md