Moderation API

Передайте один текст и до четырёх изображений, чтобы получить оценки по семи категориям от 0 до 1, отметки превышения порога и общее решение: allow, review или block. API предназначен для проверки пользовательского и сгенерированного контента: комментария перед публикацией, промпта или референса перед отправкой модели, ответа или изображения перед показом пользователю.

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

Запрос и ответ соответствуют OpenAI Moderation API, поэтому официальным SDK OpenAI достаточно заменить базовый адрес и ключ. Это проверено 13 октября 2026 года с официальным Python SDK (openai 3.29.0) для текста и изображений.

Какая модель отвечает. Поле model необязательно. Если model не указан или указано имя модели модерации OpenAI, отвечает beat-moderation-2.0. Модели beat-moderation-1.0 и beat-moderation-vision-1.0 вызываются только явно и сохраняют прежние ограничения: один текст, одно изображение либо по одному каждого типа, а также собственные пороги. Имена до 13 октября 2026 года, beat-moderation-1 и beat-moderation-vision-1, также ведут к прежним моделям. Поле model в ответе показывает фактически ответившую модель.

Beat Moderation 2.0

beat-moderation-2.0 используется по умолчанию. Модель проверяет один текст и до четырёх изображений совместно за один вызов. Категория срабатывает, если относится хотя бы к одному из них: безобидная картинка не скрывает вредную подпись, а безобидная подпись — вредную картинку. Метод и форматы запроса и ответа те же, что у прежних моделей. Передавайте только текст либо текст с изображениями:

curl https://api.beatapi.io/v1/moderations \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "beat-moderation-2.0",
    "input": [
      {"type": "text", "text": "Product photos for my shop listing."},
      {"type": "image_url", "image_url": {"url": "https://example.com/photo-1.jpg"}},
      {"type": "image_url", "image_url": {"url": "https://example.com/photo-2.jpg"}}
    ]
  }'

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(
    model="beat-moderation-2.0",
    input=[
        {"type": "text", "text": "Product photos for my shop listing."},
        {"type": "image_url", "image_url": {"url": "https://example.com/photo-1.jpg"}},
        {"type": "image_url", "image_url": {"url": "https://example.com/photo-2.jpg"}},
    ],
)
print(resp.model)               # "beat-moderation-2.0"
print(resp.results[0].verdict)  # "allow", "review" or "block"

Входные данные

• Один текст и до четырёх изображений. Не более одной текстовой части длиной до 8 000 символов и до четырёх частей image_url.
• По ссылке или внутри запроса. Изображение передаётся как общедоступная http(s)-ссылка до 2 048 символов, которую загружает BeatAPI, либо как base64 data URL.
• PNG, JPEG, WebP или GIF (первый кадр), до 16 MB каждый, с любым размером в пикселях. BeatAPI масштабирует изображения для модели и исправляет ориентацию снимков с телефона.
• Ответ 2.0 содержит "model": "beat-moderation-2.0" и "policy_version": "2026-10-15". Если переданы изображения, category_applied_input_types равно ["text", "image"]. Остальные поля описаны ниже.

Когда возвращается 400

Частичная проверка не выполняется. Запрос, отклонённый с 400, не оплачивается.

Пороги и решения

Категория отмечается, а итог становится block, при оценке 0.6, кроме исключений ниже. Решение verdict становится review начиная с оценки на 0.25 ниже порога категории, но не ниже 0.15.

Если нужны более строгие или мягкие пороги, применяйте свои значения к category_scores.

Цена и объём токенов

$0.08 за 1M входных токенов; выход бесплатный. Измеренные объёмы:

Поле usage.input_tokens каждого ответа показывает точное число учтённых токенов. Ни текст, ни изображения не сохраняются в журналах.

Быстрый старт

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_untsppzSTLTDbt7Kw360kbf4ydPBYOAS",
  "model": "beat-moderation-2.0",
  "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.99,
        "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-15",
  "usage": { "input_tokens": 1210 }
}

Категория illicit получила 0.99, что выше порога 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.99
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 content 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 content 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);
}

Изображения

Изображение передаётся в массиве input частью image_url, как в OpenAI API. Отправьте его отдельно либо добавьте связанный текст — промпт или подпись — частью text того же массива.

curl https://api.beatapi.io/v1/moderations \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      {"type": "text", "text": "Remove her clothes and make it a nude photo."},
      {"type": "image_url", "image_url": {"url": "https://beatapi.io/samples/ai-ecommerce-video-demo-poster.jpg"}}
    ]
  }'

На изображении из запроса обычный товарный плакат. Сам по себе он разрешён, но вместе с этим промптом реальный ответ был verdict: "block", с оценкой sexual равной 1 и sexual_level: "explicit". Изображение и текст проверяются совместно, а текст также оценивается отдельно, поэтому безобидная картинка не скрывает вредный запрос о ней.

resp = client.moderations.create(
    input=[
        {"type": "text", "text": "Change the background to a beach."},
        {"type": "image_url", "image_url": {"url": "https://example.com/upload.jpg"}},
    ],
)
print(resp.model)                # "beat-moderation-vision-1.0"
print(resp.results[0].verdict)   # "allow", "review" or "block"

• По ссылке или внутри запроса. Поле image_url.url принимает http(s)-ссылку либо base64 data URL, например data:image/jpeg;base64,.... Ссылку загружает BeatAPI, поэтому она должна быть общедоступна. Адрес частной сети будет отклонён.
• PNG, JPEG или WebP, до 4 MB и не больше 16 мегапикселей. Тип определяется по содержимому, а не метке data URL. Допускается base64 с переносами строк, URL-safe алфавитом или без padding.
• Одно изображение за вызов, при необходимости с одним текстом до 8 000 символов.
• Ответ изображения содержит "model": "beat-moderation-vision-1.0", "policy_version": "2026-10-13" и category_applied_input_types, равное ["image"] либо ["text", "image"] при совместном тексте. Остальные поля описаны ниже.
• Вызов занимает примерно полсекунды плюс время загрузки изображения по ссылке.

Запрос

Ответ

Ответ синхронный: успешный 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 пуст. Не стройте правила на этих полях.

Пороги и решения

У каждой проверяемой категории свой порог. Поле categories[k] показывает результат сравнения оценки с порогом, а flagged равно true, если хотя бы одна оценка достигла порога.

У Beat Moderation 2.0 свои пороги, перечисленные в начале страницы. Таблица выше относится к прежним моделям при явном выборе.

Поле sexual_level описывает сексуальный характер контента независимо от оценки:

Оценка category_scores.sexual — вероятность уровня explicit. Контент с подтекстом получает низкую оценку здесь, но sexual_level: "suggestive" и verdict: "review". Если для вас важен подтекст, читайте оба поля. Когда изображение передано с текстом, возвращается более высокий уровень из двух.

Если нужны другие пороги, примените собственные значения к category_scores.

Поле policy_version определяет политику, сформировавшую оценки. Оценки разных версий и оценки текстовой и визуальной модели несопоставимы. Сохраняйте версию рядом с каждой оценкой.

Ограничения

Здесь описаны прежние модели при явном выборе. Beat Moderation 2.0 принимает один текст и до четырёх изображений; её ограничения приведены в начале страницы.

• Один текст, одно изображение или по одному каждого типа за вызов. Несколько текстов или изображений отклоняются с 400, частичная проверка не выполняется. Отправляйте отдельный запрос на каждый элемент.
• Текст до 8 000 символов. Более длинный отклоняется с 400, а не обрезается. Разбейте его и отправьте части отдельно. Длина измеряется в кодовых единицах UTF-16, поэтому большинство эмодзи считаются за две.
• Изображение PNG, JPEG или WebP, до 4 MB и 16 мегапикселей. Иные варианты дают 400 с описанием причины.
• Аудио и видео не поддерживаются.
• Синхронный ответ. Потоковой передачи и задачи для опроса нет. Обработка на сервере занимает примерно 0.2 секунды для текста и 0.5 секунды для изображения.

Ошибки

Ошибки используют стандартный объект BeatAPI: code, message, retryable, request_id и retry_after_seconds при 429. Все коды и правила повторов приведены в разделе ошибок. В этом методе также есть поля OpenAI type и param, причём param всегда равен null, чтобы SDK OpenAI создавали привычные исключения.

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

Что означает 400 для изображения:

Повреждённое или обрезанное изображение может пройти проверки, но вызвать ошибку модели. Тогда возвращается 503 с указанием возможного повреждения файла; повтор с тем же файлом снова завершится ошибкой.

В таблице указаны исключения, реально полученные официальным Python SDK: 401, 402, 403 и 429 проверены 12 октября 2026 года (openai 2.48.0), а 400 и 503 — 13 октября 2026 года (openai 3.29.0). Ошибка 503 получена для обрезанного JPEG.

Неудачный вызов ничего не проверил: не считайте ошибку разрешением контента. Запрос с отказом 400 не оплачивается.

Оплата

Модерация оплачивается только за входные токены: $0.08 за 1M входных токенов** для используемой по умолчанию `beat-moderation-2.0`. Прежние модели при явном выборе стоят **$0.06 за 1M входных токенов для текста и $0.22 за 1M входных токенов для запроса с изображением. Все три модели есть на странице цен.

У прежних моделей политика модерации передаётся с каждым вызовом и входит во входные токены: около 1 150 токенов, поэтому даже у короткого текста есть минимальный объём. Изображение добавляет до примерно 1 000 токенов независимо от размера.

Объёмы токенов прежних моделей; значения для 2.0 приведены в начале страницы:

Поле usage.input_tokens каждого ответа показывает точное число учтённых токенов для сверки стоимости вызова.

Конфиденциальность

Отправленные текст и изображения не записываются в журналы запросов. Сохраняются только длина текста, число изображений, оценки и версия политики. Изображение по ссылке загружается один раз для конкретного запроса.

Чего API не делает

• Это классификатор, а не гарантия. Явные нарушения определяются надёжно, но завуалированный сленг, созвучия и замаскированный спам, особенно на китайском, — хуже. Проверьте реальные материалы своего продукта до внедрения.
• Пограничные изображения оцениваются менее стабильно, чем текст. Художественная нагота, единоборства и исторические фотографии часто близки к порогам; похожие изображения могут получить allow, review или block. Текст внутри картинок, например мемы и реклама с QR-кодами, в наши тесты не входил.
• sexual/minors не заменяет сопоставление хэшей известных материалов насилия над детьми и не отменяет обязанности сообщать о них по закону.
• Аудио и видео не проверяются.
• Оценки не полностью воспроизводимы. В наших тестах одинаковые вызовы различались до 0.04, поэтому близкая к порогу оценка может оказаться по любую его сторону. Рассматривайте её как пограничную.

Агенты

Агенты используют те же проверки через Capabilities API, где они зарегистрированы как model:beat-moderation-1.0 и model:beat-moderation-vision-1.0. Вход Run для текста — {"input": "…"}, для изображения — {"image_url": "…", "input": "optional text"}. Результат совпадает с описанным выше. На этом пути ошибки используют стандартный объект без type и param.

Beat Moderation 2.0 доступна как model:beat-moderation-2.0. Вход Run — {"input": "text", "image_urls": ["https://..."]}; одно изображение также можно передать через image_url.