内容审查 API

提交一段文本，拿回一个可以直接照着处理的结论：七个类别各有一个 0 到 1 的分数、各自是否过线，再加一个总的判定——allow（放行）、review（复核）或 block（拦截）。它用在用户写的和模型写的文本周围：评论发布之前、提示词送进模型之前、回复展示给用户之前。

POST https://api.beatapi.io/v1/moderations

请求和响应沿用 OpenAI Moderation API 的格式，所以 OpenAI 官方 SDK 只需改 base URL 和 API Key 就能用。2026-10-12 已用官方 Python SDK（openai 2.48.0）实测。

快速开始

curl https://api.beatapi.io/v1/moderations \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Forged ID cards and bank cards for sale, shipped within 24 hours. Message me for the price list."}'

下面是一条真实响应，当时送审的就是这样一则兜售伪造身份证和银行卡的广告。

{
  "id": "modr-task_UnzjwhQHAITmqaLLJUi3ML5gQYnRfDln",
  "model": "beat-moderation-1",
  "results": [
    {
      "flagged": true,
      "categories": {
        "sexual": false,
        "sexual/minors": false,
        "violence": false,
        "hate": false,
        "harassment": false,
        "self-harm": false,
        "illicit": true,
        "harassment/threatening": false,
        "hate/threatening": false,
        "illicit/violent": false,
        "self-harm/intent": false,
        "self-harm/instructions": false,
        "violence/graphic": false
      },
      "category_scores": {
        "sexual": 0,
        "sexual/minors": 0.01,
        "violence": 0.02,
        "hate": 0.01,
        "harassment": 0.02,
        "self-harm": 0.01,
        "illicit": 0.97,
        "harassment/threatening": 0,
        "hate/threatening": 0,
        "illicit/violent": 0,
        "self-harm/intent": 0,
        "self-harm/instructions": 0,
        "violence/graphic": 0
      },
      "category_applied_input_types": {
        "sexual": ["text"],
        "sexual/minors": ["text"],
        "violence": ["text"],
        "hate": ["text"],
        "harassment": ["text"],
        "self-harm": ["text"],
        "illicit": ["text"],
        "harassment/threatening": [],
        "hate/threatening": [],
        "illicit/violent": [],
        "self-harm/intent": [],
        "self-harm/instructions": [],
        "violence/graphic": []
      },
      "verdict": "block",
      "sexual_level": "none"
    }
  ],
  "policy_version": "2026-10-12",
  "usage": { "input_tokens": 1206 }
}

illicit 得分 0.97，高于它的拦截线 0.6，所以 categories.illicit 为 true，flagged 为 true，verdict 为 block。

OpenAI SDK（Python）

把客户端指向 BeatAPI，照常调用 moderations.create。BeatAPI 多给的字段可以直接从类型化的结果上读。

import os
from openai import OpenAI
client = OpenAI(
    api_key=os.environ["BEATAPI_API_KEY"],
    base_url="https://api.beatapi.io/v1",
)
resp = client.moderations.create(
    input="Forged ID cards and bank cards for sale, shipped within 24 hours. Message me for the price list.",
)
result = resp.results[0]
# The values in the comments are the ones from the response above.
print(result.flagged)                  # True
print(result.verdict)                  # "block" (added by BeatAPI)
print(result.categories.illicit)       # True
print(result.category_scores.illicit)  # 0.97
print(result.sexual_level)             # "none" (added by BeatAPI)
print(resp.policy_version)             # "2026-10-12" (added by BeatAPI)

JavaScript

const text = "Forged ID cards and bank cards for sale, shipped within 24 hours. Message me for the price list.";
const response = await fetch("https://api.beatapi.io/v1/moderations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BEATAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ input: text }),
});
if (!response.ok) {
  // A failed call judged nothing: do not let the text through.
  // On HTTP 429, wait the Retry-After seconds before retrying.
  throw new Error(`Moderation HTTP ${response.status}; Retry-After: ${response.headers.get("Retry-After")}`);
}
const moderation = await response.json();
const result = moderation.results?.[0];
if (!result || !["allow", "review", "block"].includes(result.verdict)) {
  throw new Error("Invalid moderation response; hold the text for review");
}
if (result.verdict === "block") {
  console.log("rejected", result.category_scores);
} else if (result.verdict === "review") {
  console.log("queued for a person", result.sexual_level, result.category_scores);
} else {
  console.log("allowed under policy", moderation.policy_version);
}

请求参数

响应

响应是同步的：HTTP 成功返回时，判定结果就在响应里，没有轮询。

类别

参与判定的有七个类别，名字和 OpenAI 的一致，各有一个 0 到 1 的分数。

OpenAI 的六个子类别键——harassment/threatening、hate/threatening、illicit/violent、self-harm/intent、self-harm/instructions、violence/graphic——都在响应里，这样按类型生成的 SDK 才能照常工作，但它们不单独判定：值固定是 false，分数固定是 0，category_applied_input_types 是空数组。不要拿它们写规则。

拦截线与判定

每个参与判定的类别都有一条拦截线：0.6，sexual/minors 是 0.3。categories[k] 就是该类别的分数和它的拦截线比较的结果；任何一个类别的分数达到拦截线，flagged 就是 true。

sexual_level 说明文本涉性的程度，与分数相互独立：

category_scores.sexual 是「露骨」这一档的概率。擦边的文本在这里得分很低，它体现在 sexual_level: "suggestive" 和 verdict: "review" 上；在意擦边内容的话，请看这两个字段。

想要比这更严或更松的线，就对 category_scores 套用你自己的阈值。

policy_version 标识给出这些分数的审查标准。不同标准版本的分数不可比，所以存分数时请把版本一起存下。

限制

• 只审文本。 带 image_url 的输入返回 400。
• 一次只审一段文本。 数组里超过一项返回 400——不会只审其中一部分。每段文本各发一次请求。
• 最长 8,000 个字符。 超长返回 400，不会截断后只审前半段；请拆开后逐段发送。长度按 UTF-16 码元计，所以多数 emoji 算两个字符。
• 同步。 没有流式，也没有需要轮询的任务。服务端处理约 0.2 秒。

错误

错误使用 BeatAPI 标准错误结构：code、message、retryable、request_id，429 时还有 retry_after_seconds。完整错误码表与重试策略见错误码。在这个接口上，错误对象还会带上 OpenAI 的 type 和 param（param 固定为 null），所以 OpenAI SDK 会照常抛出对应的异常。

{
  "error": {
    "code": "bad_request",
    "message": "input is required: the text to moderate",
    "retryable": false,
    "request_id": "…",
    "type": "invalid_request_error",
    "param": null
  }
}

表中的异常类型是 2026-10-12 用官方 Python SDK（openai 2.48.0）实际抛出的；503 那一行没有实际触发过，是按 SDK 的状态码映射写的。

调用失败就等于什么都没审——绝不能把错误当成「放行」。被 400 拒绝的请求不计费。

计费

内容审查只按输入 token 计费，单价 $0.042 / 1M 输入 token。beat-moderation-1 列在价目页上。

审查标准随每次调用一起发送，并计入输入，约 1,150 token，所以再短的文本也有一个底数：

每次响应里的 usage.input_tokens 就是这次实际计入的量，可以逐次对账。

隐私

你提交的文本不会写入请求日志。留存的只有它的长度、各类分数和审查标准版本。

它做不到的事

• 它是分类器，不是保证。 直白的违规内容判得可靠；黑话、谐音和伪装过的引流广告（尤其是中文）判得没那么可靠。依赖它之前，请先用你自己的内容测一遍。
• sexual/minors 不能代替哈希比对（针对已知的儿童性侵害材料），也不免除你的任何法定上报义务。
• 它不审图片、音频和视频。
• 分数不是完全可复现的。 我们实测，完全相同的调用之间分数最多相差 0.04，所以贴近拦截线的文本可能时而过线、时而不过。分数贴线的内容请当作临界情况处理。

供 Agent 调用

Agent 可以通过能力 API做同样的审查，它在能力目录里是 model:beat-moderation-1。Run 的入参是 {"input": "…"}，结果就是上面这个响应体。走这条路径时，错误是标准错误结构，不带 type 和 param。