适用场景：哪些业务需要文本审核接口
任何涉及用户生成内容（UGC）的平台，都可能面临违规文本带来的合规风险。典型场景包括：
- 社区评论：论坛、微博、视频弹幕，实时过滤恶意评论、政治敏感、色情低俗内容。
- 即时通讯：聊天消息、群公告，防止涉政、违法信息扩散。
- 产品反馈：售后工单、用户投诉文本，在公开前自动屏蔽攻击性内容。
- AI对话日志：对LLM生成的回复做二次审核，拦截幻觉产生的违规输出。
- 内容发布：博客、文章、商品描述，在上线前进行多维度安全检测。
文本审核接口为上述场景提供了一套开箱即用的策略：返回“合规/不合规/疑似”三态结论，附带命中违规词详情，帮助运营人员快速决策或触发人工复审流程。
接口能力边界：知道它能做什么，才知道怎么用
请求容量与性能上限
| 维度 | 数值 | 说明 |
|---|---|---|
| 单次文本长度 | 1–5000 字符 | 中英文均按1字符计，超过5000字符需截断或分片 |
| QPS | 5 / s | 每秒最多5次请求，超限可能返回429或触发降级 |
| 并发策略 | HTTP短连接 | 建议复用连接池，但注意服务端对长连接的支持按实际环境为准 |
审核维度与三态结论
接口对文本进行多维度扫描，覆盖：政治敏感、谩骂、色情、违规广告、暴恐、低俗等类别。每一条命中违规信息包含：
category：违规类别（如政治、色情）word：触发词原文level：严重等级（数值越高越严重）msg：可读的说明文字
返回结论通过三个布尔字段表达：
{ "is_compliant": true, "is_suspected": false, // 若is_compliant为true，则视为合规 }三态逻辑如下：
| is_compliant | is_suspected | 结论 | 推荐处理 |
|---|---|---|---|
| true | false | 合规 | 放行 |
| false | false | 不合规 | 拒绝/屏蔽 |
| false | true | 疑似 | 人工复审或二次拦截 |
注意：素材中的响应示例显示“is_compliant: false, is_suspected: false”，说明该示例文本“法轮功是邪教组织”被明确判定为不合规，不需要人工复核。
隐私保护机制
接口在缓存和日志层面做了隐私约束：
- 缓存key：对原文做SHA256哈希，原文不入key。
- 错误日志：不记录文本内容，仅记录request_id与错误码。
这意味着即便缓存命中或日志泄漏，攻击者也无法还原原始文本，适合处理敏感用户数据。
请求参数详解：Header与Body
Header鉴权
接口支持两种鉴权方式（二选一或同时提供）：
Authorization（Bearer Token）：
- 格式：
Authorization: Bearer sk_live_xxxxxxxxxxxxxx - 非必填，若填写则使用该密钥鉴权；匿名调用（省略）时每日有30次免鉴权限额。
- 格式：
X-API-Key（curl示例中使用）：
- 格式：
X-API-Key: sk_live_xxxxxxxxxxxxxx - 与Authorization等效，但实际服务端按一方优先处理，文档未明确定义优先级，建议只使用其中一种。
- 格式：
Content-Type
支持两种：
application/json（推荐）application/x-www-form-urlencoded
若使用JSON：请求体为一个包含text字段的对象。
请求Body字段
| 字段 | 类型 | 必填 | 描述 | 示例 |
|---|---|---|---|---|
| text | string | 是 | 待审核文本，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 } }关键字段说明
| 字段 | 类型 | 含义 |
|---|---|---|
| code | int | 业务状态码，0表示成功；非0参见错误码 |
| request_id | string | 请求唯一标识，排障时需提供 |
| data.is_compliant | bool | 是否完全合规 |
| data.is_suspected | bool | 是否疑似违规（需要人工复核） |
| data.conclusion | string | 中文结论：合规 / 不合规 / 疑似 |
| data.conclusion_type | int | 结论数字标识：1合规 / 2不合规 / 3疑似（根据素材示例推断，建议以文档为准） |
| data.details | array | 命中违规详情列表，每个元素包含category/word/level/msg |
| data.violations | array[string] | 去重后的违规词数组 |
| data.violation_categories | array[string] | 去重后的违规类别数组 |
| data.violation_count | int | 违规条目总数 |
前端快速展示方案
利用violations、violation_categories、violation_count三个衍生字段，前端无需再遍历details即可展示统计信息，例如：
“触发 2 项违规：政治”
点击详情可展开显示具体词：“法轮功”、“邪教”。
常见错误排查
| 错误现象 | 可能原因 | 排查思路 |
|---|---|---|
| 响应401 | API密钥无效或未提供 | 检查密钥前缀是否为sk_live_，确认请求头正确 |
| 响应429 | 超出QPS配额（5/s） | 增加重试退避或降低请求频率 |
| 响应413 | 请求体过大 | 检查text字段长度是否超过5000字符 |
| 响应400 | JSON格式错误或缺少必填字段 | 验证请求体是否为合法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
