批量端点 在单个 POST 中让最多 20 条文本通过 Telm 反垃圾引擎，为每一条返回一个裁决。它仅用规则（无 AI 层），在 Pro 套餐及以上可用。配额按每项计费，因此十条文本的一个批次花费十次调用。对于带可选 AI 检查的单条文本，使用常规的垃圾检查端点。
1批量垃圾检查做什么
批量垃圾检查让你一次为许多条文本评分，而不是每条消息发一个请求。你向 /spam/check-batch 发送一个带项目数组的 POST，并按相同顺序取回一个裁决数组——非常适合分类积压的消息、审核评论流，或在样本上评估检测质量。
该批次运行的是保护实时群组的同一个规则引擎，但它不运行 AI 层，这让每个请求保持快速和可预测。如果你需要 AI 检查，使用单条的 垃圾检查端点 并启用 AI 选项，一次一条文本。
- 端点：POST /api/public/v1/spam/check-batch。
- 每个请求为最多 20 条文本评分，裁决按输入顺序返回。
- 仅规则：批量模式下不运行 AI 层。
2请求格式
请求主体是一个带 items 数组的 JSON 对象。每一项有一个必需的 text 字段和一个可选的 context 对象，后者镜像实时引擎所看到的内容——group_id、发送者 user_telegram_id、发送者是否为新用户、username，以及诸如 allow_sales 和 crypto_community 之类的标志。
当一项在其 context 中包含 group_id 时，检查会应用该群组的自定义规则和设置，因此你的账户必须是该群组的管理员，否则整个请求会被拒绝。省略群组上下文则改为对照全局规则集评分。
- 顶层字段：items——一个含一到二十个条目的数组。
- 每一项：text（必需）和一个可选的 context 对象。
- context 可携带 group_id、user_telegram_id、is_new_user、username、allow_sales、crypto_community。
- 一个群组上下文要求你管理该群组。
3响应格式
响应是一个 JSON 对象，带一个 results 数组——每个输入项一个裁决，按相同顺序——以及一个显示你已用计数、每日限制和重置时间的 quota 对象。
每个裁决告诉你分类及其原因。verdict 字段是 spam、suspicious 或 clean 之一。在它旁边你会得到一个数值 score 和 confidence、一个 recommended_action（none、review、warn、mute、kick、ban 或 delete 之一）、一个 categories 列表、人类可读的 reasons、匹配的 matched_rules 的名字，以及一个带各个评分贡献的 signals 映射。
- results——每一项一个裁决，按输入顺序。
- verdict——spam、suspicious 或 clean。
- 每个裁决还有 score、confidence、recommended_action、categories、reasons、matched_rules 和 signals。
- quota——used、limit 和 reset_at，在主体中回显。
4限制与配额成本
一个批次每个请求上限为 20 项，且每条文本被限制为 10,000 个字符。整个请求主体也有一个大小上限，因此非常大的载荷会在处理之前被拒绝。如果你有超过 20 条文本，就把它们拆分到多个请求中。
配额按每项而非每请求计费：十条文本的一个批次会从你的每日配额中花费十次调用。这与 API 速率限制与配额 中描述的是同一个预算，且响应会携带通常的 X-Quota-Limit、X-Quota-Used 和 X-Quota-Reset 头。
- 每个请求最多 20 项；每条文本最多 10,000 个字符。
- 配额成本等于批次中的项目数。
- 标准的 X-Quota-* 头适用，外加主体中的一个 quota 对象。
5错误与超时
错误请求返回 400，带一个特定的码：空的 items 数组、超过项目上限的批次、缺失的 text，或超过长度限制的文本。一个你不管理的群组上下文会为该项返回 404。一个低于 Pro 的套餐返回 403，带一个 plan_required 码。
如果处理一个批次超出了它的时间预算，API 会返回 504 并为它未完成的项目退还配额，因此你只为已完成的工作付费。如果你看到超时，就发送更小的批次。
- 400——empty_batch、batch_too_large、missing_text 或 text_too_long。
- 404——一项上下文中的某个群组不是你管理的。
- 403 plan_required——批量端点需要 Pro 或更高。
- 504 timeout——批次运行太久；未完成的项目被退还。发送更少的文本。