组合式多重检查请求

你不需要为每一种检查各调用一次 API。单个 POST /api/v2/check 就可以对混合内容同时执行文本、图片、敏感词和杀毒检查，并返回一份包含各项结果的响应。这是审核一条同时包含标题/说明文字、图片和附件的帖子时最高效的方式。

为什么要在一次调用中审核所有内容？

用户提交的内容通常是一组组合：文本加媒体加链接。分别为每个部分调用 API，意味着更多往返请求、更高延迟，也会消耗更多配额。一次组合请求会并行运行已启用的检查，并给出一个可直接处理的统一判定。

如何一次运行多项检查？

把每种内容放入 content，在 settings 中启用你需要的检查，然后读取各项检查结果。每个已启用的检查都会针对匹配的内容运行。

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "content": {
      "text": "Great deal, check my profile!",
      "image_urls": ["https://example.com/post-image.jpg"],
      "document_urls": ["https://example.com/attachment.pdf"]
    },
    "settings": {
      "check_spam": true,
      "check_sentiment": true,
      "check_images": true,
      "check_antivirus": true
    }
  }'

响应

{
  "has_violations": true,
  "cached": false,
  "results": {
    "hits": true,
    "spamfinder": { "label": "spam", "confidence": 0.91, "is_spam": true, "hit": true },
    "sentiment": { "is_negative": false, "is_toxic": false, "score": 0.1, "hit": false },
    "images": { "status": "OK", "porn": 0.02, "sexual": 0.05, "neutral": 0.93, "hit": false },
    "antivirus": { "status": "OK", "hit": false, "details": [] }
  },
  "usage": {
    "api_requests_used": 530,
    "api_requests_limit": 10000,
    "api_requests_remaining": 9470
  }
}

如何解读组合结果？

使用 has_violations 做整体判断，然后查看各个 results.<check>.hit，了解是哪项检查触发以及原因：

字段	含义
has_violations	如果任一已启用检查标记了该内容，则为 True——这是你的一句话判定
results.hits	位于结果对象内部的同一个整体信号
results.spamfinder.hit	触发了垃圾内容检查（会考虑阈值；应以 hit 作为关口，而不是原始的 is_spam）
results.sentiment.hit	有毒/负面情绪超过了你的阈值
results.images.hit	某张图片超过了你的 NSFW 阈值
results.antivirus.hit	在文档中发现恶意软件
results.badwords.hit	命中了已配置的敏感词
results.skipped_features	已请求但未运行的检查（例如某个功能的配额已用尽）

只有你启用的检查（且存在匹配内容）才会出现在 results 中。没有可处理内容的检查——例如启用了 check_images 但没有 image_urls——会直接不运行。

哪些内容对应哪些检查？

检查	读取的内容
check_sentiment, check_spam, check_badwords, check_language	content.text
check_images	content.image_urls
check_antivirus	content.document_urls

单个请求最多可携带 10 个图片 URL、5 个文档 URL，以及最多 10,000 个字符的文本。请把一次提交的各个部分放在一起发送，而不是拆成多次调用。

部分失败怎么办？

如果某项检查出错（比如图片 URL 无法访问），其他检查仍会返回——你会得到已成功检查的结果，而失败的检查会报告错误/空结果，不会让整个请求失败。按检查逐项决策：对已确认的 hit 进行拦截，并决定出错的检查是放行还是加入审核队列。

最佳实践

只启用你需要的检查

每启用一项检查都会增加处理工作。开启与你实际接收内容相匹配的检查即可——对纯文本消息运行 check_antivirus 没有任何收益。

先做统一判定，再深入查看

先根据 has_violations 分支处理快速路径，只有在需要知道是哪项检查触发时（用于日志、申诉或分派给合适的审核人员），再检查 results。

const res = await check(content, settings);
if (!res.has_violations) return allow();

const r = res.results;
if (r.antivirus?.hit) return quarantine();      // most severe first
if (r.images?.hit)    return blockMedia();
if (r.spamfinder?.hit || r.badwords?.hit) return shadowban();
return queueForReview(r);

相关内容

• 文本分析 — 情绪、垃圾内容，以及文本结果字段
• 图片 NSFW 检测 — 图片评分与阈值
• 文件杀毒扫描 — 文档恶意软件检查
• 错误和响应代码 — 响应封装与配额处理