OpenAI Moderation API 怎么用？

官方资料（2026-10-31 核对）：Moderation guide · Create moderation reference · omni-moderation-latest model · Deprecations

Moderation API 能审核什么？

OpenAI 当前把 Moderation 定位为有害内容分类能力。你可以单独把文本或图片提交到 Moderation 端点，也可以在生成请求中附带审核配置，取得输入与完整输出的审核信号。当前 omni-moderation-latest 支持文本和图片，不支持音频；Moderation 端点当前免费，图片文件上限为 20 MB。

若是已知或疑似 CSAM，不要发送给 Moderation API。官方明确说明它不是 CSAM 检测或处置系统，也不能替代专门的儿童安全保障与报告流程。

最小可用调用：先在服务端审核文本

API Key 必须保存在服务端环境变量中。下面示例把用户文本提交给官方 SDK，读取第一条结果；生产代码还要补充鉴权、超时、日志脱敏和错误策略。

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

const moderation = await openai.moderations.create({
  model: "omni-moderation-latest",
  input: userText
});

const result = moderation.results[0];

if (result.flagged) {
  return {
    action: "review",
    categories: result.categories
  };
}

return { action: "allow" };

端点是 POST /v1/moderations。API Reference 当前仍列出旧的 text-moderation-* 名称，但官方弃用页显示这些旧模型已在 2025-10-27 停用；新实现应使用 omni-moderation-latest，若需要稳定行为可评估官方列出的快照。

文本和图片怎样一起审核？

多模态 input 是一个对象数组。文本项使用 type: "text"，图片项使用 type: "image_url"。远程图片地址必须能被服务读取；Base64 图片使用 Data URL。不要只看总的 flagged，还要确认每个类别实际应用到 text、image 还是两者。

const moderation = await openai.moderations.create({
  model: "omni-moderation-latest",
  input: [
    {
      type: "text",
      text: userCaption
    },
    {
      type: "image_url",
      image_url: {
        url: "https://example.com/upload.png"
      }
    }
  ]
});

const result = moderation.results[0];
console.log({
  flagged: result.flagged,
  categories: result.categories,
  scores: result.category_scores,
  appliedTo: result.category_applied_input_types
});

四个结果字段应该怎样读？

当前类别包括 harassment、hate、illicit、self-harm、sexual、violence 及部分细分类别。harassment、hate、illicit 与 sexual/minors 等类别是文本限定；self-harm、sexual、violence 及其部分细分类别支持文本和图片。纯图片输入遇到文本限定类别时，官方说明会返回 0 分。

怎样设计阈值和人工复核？

1. 先定义动作，不先拍脑袋定数字：区分允许、提示、限制功能、人工复核、拒绝与紧急处置。
2. 按类别与场景拆开：公开发布、私聊、搜索、工具执行和支付动作的容错成本不同。
3. 准备代表性评测集：包含正常内容、边界内容、明确违规内容与常见语言变体，并记录人工标签。
4. 计算误报与漏报：按类别查看 precision、recall 和业务损失，不用一个阈值覆盖全部类别。
5. 记录模型标识：若依赖分数阈值，升级模型或切换快照后重新跑评测。
6. 保留复核和申诉：尤其是高影响账户动作，不应只凭一次自动分类直接永久处罚。

输入审核、输出审核和工具调用怎样排顺序？

生成 API 的内联审核会给输入和完整输出返回审核容器，但模型仍会正常生成；应用必须在展示或执行下游动作前读取结果。工具调用场景中，官方说明对话内容里的工具参数与工具输出可以被覆盖，但工具名、描述、Schema 和 response-format Schema 不在审核范围内。因此 Function Calling 仍需参数校验、最小权限和显式授权。

流式输出尤其要谨慎：审核分数在完整输出后才到达，不会随每个 partial delta 返回。如果界面立即展示每个增量，用户可能先看到尚未审核的内容；可按风险选择短缓冲、完整输出后展示或使用其他分层策略。具体流式状态机见 OpenAI API Streaming 指南。

审核失败时怎样降级？

以下是应用设计建议，不是 OpenAI 为所有业务规定的统一规则：

• 高风险写操作：审核超时或返回错误时停止动作、限制能力或转人工，不把“没有结果”当作“安全”。
• 低风险只读场景：可根据风险承受能力提供受限降级，但要明确哪些内容和功能仍被禁止。
• 统一错误模型：为超时、429、5xx、无效输入和图片抓取失败分别记录状态，不在日志中保存完整敏感正文。
• 监控：跟踪审核调用成功率、延迟、flagged 比例、各类别分布、人工推翻率和模型版本。
• 演练：模拟 Moderation 服务不可用、图片过大、远程 URL 失效和模型行为变化。

API 请求本身的 429、500、503 和超时仍按 429 速率限制与 5xx/超时指南处理；不要无限重试，也不要在浏览器暴露 Key。

上线前检查清单

• 服务端调用 /v1/moderations，API Key 未进入前端、Git 或日志。
• 使用 omni-moderation-latest 或经过评测的官方快照，不再依赖已停用的 text-moderation 模型。
• 文本、图片和混合输入均有真实样本测试；图片大小与抓取失败有明确错误。
• 代码同时读取 flagged、categories、category_scores 与 category_applied_input_types。
• 每个类别都有允许、复核、拒绝或降级动作，且动作与风险相称。
• 自定义阈值有版本化评测集、误报/漏报指标和重新校准计划。
• 输入、输出、工具参数与工具结果的检查位置清楚，审核不替代权限和 Schema 校验。
• Streaming 不会在完整审核结果到达前无条件展示高风险增量。
• 超时、429、5xx 和审核错误有 fail-closed、受限降级或人工路径。
• 高影响决定保留人工复核、申诉、审计与隐私最小化。

常见问题

本文核对日期为 2026-10-31。模型、类别、费率、限制和字段可能调整，上线前请再次读取官方 Moderation 指南、模型页与 API Reference。