适用场景文本审核接口适用于需要实时或近实时检测用户生成文本中违规内容的业务场景例如社交平台评论 / 帖子发布前预审即时通讯消息过滤社区论坛内容发布审核直播弹幕关键词拦截反馈 / 投诉文本自动分类这类场景对接口的调用频率、单次请求长度以及鉴权方式有严格的边界约束本文将围绕这些边界展开说明。接口能力边界QPS 限制接口的读写共享 QPS 为5 次/秒。超过该频率的请求将返回429 Too Many Requests建议客户端在发请求前做本地限速例如使用令牌桶算法或采用异步队列控制并发。单次请求文本长度最大长度5000 字符中英文均按 1 字符计算最小长度1 字符空字符串会返回参数错误超过 5000 字符时接口返回400 Bad Request错误信息提示字段超长。鉴权限制接口支持两种鉴权模式模式Header 示例说明API Key 鉴权Authorization: Bearer sk_live_xxxxxxxxxxxxxx无调用次数限制受 QPS 约束匿名调用不传Authorization头每日最多30 次调用超出后返回403 Forbidden匿名调用额度适用于快速验证和原型开发生产环境应使用 API Key。数据隐私与缓存缓存 key 使用sha256(text)哈希原始文本不会出现在缓存键中错误日志不记录输入的文本原文响应中返回的text字段为请求时的原文仅用于核对请求参数与鉴权请求信息请求方法POST请求地址https://v1.apizero.cn/api/text-censorContent-Type支持application/json或application/x-www-form-urlencodedHeader 参数参数必填类型说明Authorization否stringAPI Key 鉴权格式Bearer sk_live_xxx匿名调用时不传Content-Type否string默认application/json请求体JSON 示例{ text: 今天天气不错适合出门散步。 }字段说明字段类型必填说明textstring是待审核文本1–5000 字符中英文均按 1 字符计可复制的 curl 示例1. 使用 API Key 鉴权推荐# 替换 YOUR_API_KEY 为真实的 sk_live_xxx 密钥 curl -sS -X POST \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d {text: 法轮功是邪教组织} \ https://v1.apizero.cn/api/text-censor2. 匿名调用每日 30 次# 不传 Authorization 头系统自动视为匿名调用 curl -sS -X POST \ -H Content-Type: application/json \ -d {text: 今天天气不错适合出门散步。} \ https://v1.apizero.cn/api/text-censor返回结果中text字段会原样回显请求的文本可用于前端核对。返回值解读响应采用统一 JSON 结构示例{ code: 0, msg: 成功, request_id: abc123def456, data: { text: 法轮功是邪教组织, text_length: 8, is_compliant: false, is_suspected: false, conclusion: 不合规, conclusion_type: 2, details: [ { category: 政治, level: 3, msg: 存在政治内容不合规, word: 法轮功 }, { category: 政治, level: 3, msg: 存在政治内容不合规, word: 邪教 } ], violations: [法轮功, 邪教], violation_categories: [政治], violation_count: 2 } }顶层字段字段类型说明codeint0 表示成功非 0 为错误码msgstring状态描述request_idstring唯一请求 ID可用于日志排查dataobject审核结果数据data 对象字段字段类型说明textstring原始请求文本text_lengthint文本长度字符数is_compliantbooltrue 表示完全合规is_suspectedbooltrue 表示疑似违规需人工复核conclusionstring结论描述「合规」「不合规」「疑似」conclusion_typeint1合规2不合规3疑似detailsarray详细命中信息每个元素包含category、level、msg、wordviolationsarray命中违规词去重后的列表violation_categoriesarray命中类别去重后的列表violation_countint总违规条数按命中词去重前计数三态结论is_complianttrue放行is_compliantfalse is_suspectedfalse拒绝is_suspectedtrue进入人工队列。常见错误处理状态码错误场景排查建议400请求体格式错误、text为空或超过 5000 字符检查 JSON 格式确保 1 ≤ len(text) ≤ 5000401API Key 格式错误或过期确认Authorization头以Bearer开头且密钥有效403匿名调用超出每日限制或 API Key 权限不足切换为有效 API Key 或等待额度重置429超过 QPS 5/s降低请求频率加入退避重试逻辑5xx服务端内部错误重试请求若持续发生请联系技术支持工程化注意事项1. 线程安全与并发控制使用Semaphore或RateLimiter限制每秒请求数 ≤ 5批量文本建议按 5 个/秒的速率依次发送避免瞬时超限2. 重试策略对429和5xx错误采用指数退避如 1s、2s、4s最多重试 3 次3. 文本长度预处理前端提交前先校验长度超长文本做截断或分片注意分片可能破坏语义后端应再次校验防止绕过前端限制4. 隐私日志处理接口本身设计已保证缓存 key 为原文哈希、错误日志不记录文本业务方也应避免在应用日志中打印text原文仅记录request_id和结论5. 疑似结果的人工流转对is_suspectedtrue的文本生成工单进入人工审核队列设计人工审核结果回调机制反向异步更新数据库审核状态6. 监控与告警监控429出现频率及时调整客户端限流参数监控5xx比例超过阈值触发告警记录violation_rate违规文本占比用于业务内容安全趋势分析参考文档接口原始文档https://apizero.cn/aidocs/text-censor/raw.md文档页面https://apizero.cn/aidocs/text-censor