API модерации изображений: руководство с примерами на Python и JavaScript

API модерации изображений принимает картинку, оценивает её по списку категорий вреда и подсказывает, что с ней делать: опубликовать, придержать или заблокировать. Подвох универсальной модели вроде omni-moderation-latest в том, что не каждая категория в её ответе действительно смотрит на изображение: в документации OpenAI 6 из 13 категорий помечены как «Text and images», а остальные 7 как «Text only»^[1]. Если отправить фотографию без подписи, эти 7 чисто текстовых категорий вернут 0 по самой конструкции модели, а не потому, что фото безопасно^[1].

В этом руководстве разобрано, что это значит на практике: на какие категории можно опираться для изображений, как отправить картинку (reAPI принимает только публичные URL), как тарифицируется запрос, как превратить оценки в решения, а также рабочий пример на Python и JavaScript, который отправляет изображение и опрашивает задачу до получения вердикта. В конце показано, чем отличаются специализированные сервисы для изображений: Sightengine, Hive, Azure AI Content Safety и Amazon Rekognition.

TL;DR

• omni-moderation-latest оценивает изображения по 6 категориям: sexual, self-harm, self-harm/intent, self-harm/instructions, violence и violence/graphic. Остальные 7, включая sexual/minors, работают только с текстом^[1].
• В reAPI изображение передаётся блоком image_url с публичным http(s) URL. Base64 и URI data: отклоняются^[2].
• Оплата идёт за единицы модерации: одна единица за изображение, одна за каждые 1000 слов текста, минимум одна единица за запрос^[2]. Актуальные ставки указаны на странице модели.
• Вызов асинхронный: POST /api/v1/moderations, затем опрос GET /api/v1/tasks/{id}, пока status не станет completed^[2].
• flagged означает вердикт модели по умолчанию. Для собственной политики задайте пороги category_scores (от 0 до 1) для каждой категории и перекалибруйте их, когда модель обновится^[1].
• Бесплатен ли собственный эндпоинт OpenAI, разобрано в статье Is the OpenAI moderation API free?.

Какие категории вреда видит API модерации изображений

OpenAI перечисляет, какие типы входных данных поддерживает каждая категория omni-moderation-latest^[1]:

Для конвейера обработки изображений из этого следуют два важных вывода.

Во-первых, ноль не всегда является результатом измерения. OpenAI указывает, что если отправить только изображения без сопроводительного текста, модель вернёт оценку 0 для категорий, работающих только с текстом^[1]. Символ ненависти в меме или письменная угроза на скриншоте не будут пойманы оценками hate или harassment в запросе, содержащем только изображение. В поле category_applied_input_types ответ сообщает, по каким типам входных данных оценивалась каждая категория; в примере OpenAI с одним изображением шесть категорий для картинок содержат ["image"], а остальные пустой массив^[1]. Проверяйте это поле, прежде чем считать низкую оценку пропуском.

Во-вторых, sexual/minors работает только с текстом^[1]. В руководстве OpenAI также сказано, что не следует отправлять в Moderation API известные или предполагаемые материалы сексуального насилия над детьми: API не предназначен для обнаружения CSAM и не заменяет специализированные средства защиты детей^[1]. Если ваша платформа принимает загрузки от пользователей, предусмотрите отдельный механизм защиты детей.

OpenAI документирует для модели ограничение на размер файла изображения в 20 МБ^[1].

Отправка изображений: только публичные URL

В теле запроса одно поле с контентом, input. Для изображений в нём передаётся массив блоков контента^[2]:

{
  "model": "omni-moderation-latest",
  "input": [
    { "type": "image_url", "image_url": { "url": "https://example.com/upload.jpg" } }
  ]
}

Собственный справочник API OpenAI говорит, что image_url.url может быть либо URL изображения, либо данными изображения в кодировке base64^[3]. reAPI принимает только первый вариант: image_url.url должен быть публичным http(s) URL, а base64 или URI data: не проходят валидацию с ошибкой 20003^[2]. Это правило действует для медиаданных на входе всех моделей reAPI.

Для пользовательских загрузок порядок действий такой: сохранить файл, получить URL, доступный из интернета, затем отправить его на модерацию. Подписанные URL подходят, если они ещё действительны в момент выполнения задачи^[2]. Если URL не удаётся загрузить, задача завершается ошибкой 80007, а списанная сумма возвращается^[2]. Держите объект приватным и неопубликованным, пока не придёт вердикт.

Подпись и фотографию можно также положить в один массив. В документации reAPI отмечено, что массив блоков контента возвращает один результат на весь набор, то есть модель оценивает текст и изображение вместе^[2]. Для поста с подписью это именно то, что нужно. Для десяти не связанных между собой загрузок это не подходит: по одному общему вердикту не понять, какое изображение его вызвало, поэтому отправляйте их отдельными запросами.

Как тарифицируется модерация изображений

reAPI тарифицирует omni-moderation-latest за единицы модерации^[2]:

Единицы пересчитываются в кредиты один раз на запрос с округлением вверх, опрос бесплатен, а за неудачные запросы средства возвращаются автоматически^[2]. Один запрос принимает до 500 элементов^[2]. Ставка за единицу указана на странице модели. Сравнение цен и бесплатных лимитов у разных поставщиков приведено в статье Is the OpenAI moderation API free?.

Пример API модерации изображений на Python и JavaScript

Оба примера делают одно и то же: отправляют одно изображение, опрашивают задачу каждые 3 секунды и возвращают первый результат. Документация reAPI по задачам рекомендует опрашивать не чаще чем раз в 2–3 секунды, потому что эндпоинт опроса кешируется на 5 секунд, пока задача выполняется^[4]. Проверка модерации обычно завершается за несколько секунд^[2].

Python

import time
import requests

API = "https://reapi.ai/api/v1"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

def moderate_image(image_url, timeout_s=60):
    submit = requests.post(
        f"{API}/moderations",
        headers=HEADERS,
        json={
            "model": "omni-moderation-latest",
            "input": [{"type": "image_url", "image_url": {"url": image_url}}],
        },
        timeout=30,
    )
    submit.raise_for_status()
    task_id = submit.json()["id"]

    deadline = time.time() + timeout_s
    while time.time() < deadline:
        time.sleep(3)
        task = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=30).json()
        if task["status"] == "completed":
            return task["output"]["moderation"]["results"][0]
        if task["status"] == "failed":
            raise RuntimeError(f'{task["error"]["code"]}: {task["error"]["message"]}')
    raise TimeoutError(f"task {task_id} still processing")

result = moderate_image("https://example.com/upload.jpg")
print(result["flagged"], result["category_scores"]["violence"])

JavaScript (Node.js 18+, сохранить как модуль .mjs)

const API = "https://reapi.ai/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.REAPI_API_KEY}`,
  "Content-Type": "application/json",
};

async function moderateImage(imageUrl, timeoutMs = 60_000) {
  const submit = await fetch(`${API}/moderations`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      model: "omni-moderation-latest",
      input: [{ type: "image_url", image_url: { url: imageUrl } }],
    }),
  });
  if (!submit.ok) throw new Error(`submit failed: ${submit.status} ${await submit.text()}`);
  const { id } = await submit.json();

  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    await new Promise((r) => setTimeout(r, 3000));
    const task = await (await fetch(`${API}/tasks/${id}`, { headers })).json();
    if (task.status === "completed") return task.output.moderation.results[0];
    if (task.status === "failed") throw new Error(`${task.error.code}: ${task.error.message}`);
  }
  throw new Error(`task ${id} still processing`);
}

const result = await moderateImage("https://example.com/upload.jpg");
console.log(result.flagged, result.category_scores.violence);

Запускайте JavaScript-версию на сервере, а не в браузере. API-ключ является Bearer-токеном, и если он попадёт во фронтенд-код, его увидит любой, кто откроет инструменты разработчика. То же касается вопроса про React в разделе FAQ ниже. Полная схема запроса, включая текст и смешанные входные данные, приведена в документации API.

Чтение результата и настройка порогов

Каждый результат содержит четыре поля^[1][2]:

flagged годится для первого прохода, но в нём заложены настройки модели по умолчанию, которые могут оказаться строже или мягче вашей политики^[2]. OpenAI рекомендует воспринимать оценки как сигналы для политики вашего приложения, а не как автоматическое решение о блокировке, и при необходимости направлять помеченный контент на проверку^[1].

Распространённая схема: три диапазона для каждой категории изображений. Ниже низкого порога контент пропускается, в середине уходит на ручную проверку, выше высокого порога блокируется. Минимальный вариант:

IMAGE_CATEGORIES = [
    "sexual", "self-harm", "self-harm/intent", "self-harm/instructions",
    "violence", "violence/graphic",
]
REVIEW_AT = 0.3   # example values only; calibrate on your own labeled images
BLOCK_AT = 0.8

def decide(result):
    applied = result["category_applied_input_types"]
    scores = result["category_scores"]
    checked = [c for c in IMAGE_CATEGORIES if "image" in applied.get(c, [])]
    top = max((scores[c] for c in checked), default=0.0)
    if top >= BLOCK_AT:
        return "block"
    if top >= REVIEW_AT or result["flagged"]:
        return "review"
    return "allow"

Числа выше даны для иллюстрации и не являются рекомендацией. Подберите свои, прогнав несколько сотен уже размеченных вами изображений и посмотрев, где ложатся оценки. Периодически повторяйте эту проверку: OpenAI сообщает, что планирует и дальше обновлять базовую модель и что собственные политики на основе category_scores со временем может потребоваться перекалибровать^[1]. При прохождении через reAPI оценки не округляются и не пересчитываются^[2], поэтому однажды выполненная калибровка напрямую применима к значениям, которые читает ваш код.

Чем отличаются специализированные API модерации изображений

Универсальная модель и специализированный сервис для изображений отвечают на разные вопросы. omni-moderation-latest оценивает шесть визуальных категорий и может оценивать подпись вместе с изображением^[1]. Специализированные API для изображений распознают гораздо больше визуальных классов, например оружие, наркотики, символы ненависти или текст на изображении, и различаются тем, как принимают файл и как сообщают уверенность. По документации каждого поставщика:

Выбор обычно определяют три различия.

Визуальный охват. Если нужно ловить оружие, наркотики, символы ненависти или текст, впечатанный в изображение, специализированные сервисы явно перечисляют эти классы^[5][8][13]. У omni-moderation-latest для них нет категорий изображений^[1].

Форма оценки. Hive возвращает уверенность 0–1 по каждому классу и советует начинать примерно с 0.90 для пометки класса^[8]. Rekognition отбрасывает метки ниже MinConfidence, который по умолчанию равен 50 по шкале 0–100^[14]. Azure для изображений возвращает грубые уровни серьёзности: 0, 2, 4 или 6^[11]. Порог, подобранный на одном сервисе, не переносится на другой.

Приём входных данных. Azure и Rekognition принимают байты в base64^[10][14], а Sightengine и Hive принимают прямую загрузку файла^[6][9]. reAPI принимает только URL^[2], что удобно для конвейеров, где загрузка и так попадает в объектное хранилище.

omni-moderation-latest подходит, если ваш контент в основном текстовый с прикреплёнными изображениями, если шесть визуальных категорий соответствуют вашей политике или если вы уже вызываете другие модели через reAPI тем же ключом. Более широкое сравнение по модальностям и сценариям приведено в статье Best content moderation API.

Часто задаваемые вопросы

API модерации изображений бесплатно

OpenAI заявляет, что её собственный эндпоинт модерации бесплатен^[1]. В reAPI omni-moderation-latest оплачивается по факту использования, одна единица за изображение, а за неудачные запросы средства возвращаются^[2]. Бесплатные уровни и лимиты запросов у разных поставщиков сравниваются в статье Is the OpenAI moderation API free?.

Бесплатный API модерации загруженных изображений

Модерация загрузки состоит из трёх шагов: сохранить файл приватно, создать URL, который API сможет загрузить (подписанный URL подходит, пока он действителен), затем отправить этот URL и публиковать только после вердикта^[2]. reAPI не принимает байты файла или строку base64 напрямую^[2]. Какие сервисы дают бесплатный объём, смотрите в статье Is the OpenAI moderation API free?.

OpenAI API модерации изображений

Да, модель модерации OpenAI работает с изображениями. omni-moderation-latest принимает текст и изображения, не классифицирует аудио и оценивает изображения только по категориям sexual, self-harm и violence^[1]. ID модели в reAPI тот же, omni-moderation-latest, и доступна она через асинхронный эндпоинт задач^[2].

API модерации изображений Python

Пример на Python выше полный: он отправляет блок image_url на /api/v1/moderations, опрашивает /api/v1/tasks/{id} и возвращает output.moderation.results[0]. Ему нужен только пакет requests. В документации API тот же вызов показан на cURL, Node.js и Go.

API модерации изображений React

Вызывайте API модерации со своего бэкенда, а не из компонента React. Ваше React-приложение загружает файл на ваш сервер или в хранилище, сервер вызывает API с ключом, а клиент получает только решение. Bearer-ключ в браузерном коде виден каждому посетителю.

Может ли ChatGPT API анализировать изображения?

Да. Модели OpenAI с поддержкой зрения анализируют изображения через Responses API и Chat Completions API по URL, data URL в base64 или ID файла^[16]. Это свободное понимание изображений. Для фиксированного набора категорий вреда с оценками 0–1 специально предназначен эндпоинт модерации^[1].

Лучший API модерации изображений

Зависит от того, что нужно обнаруживать. Универсальная модель вроде omni-moderation-latest покрывает сексуальный контент, самоповреждение и насилие на изображениях и добавляет текстовые категории для подписей^[1]; специализированные сервисы для изображений покрывают больше визуальных классов (см. таблицу выше). Полное руководство по выбору приведено в статье Best content moderation API.

Как встроить модерацию изображений в процесс загрузки

Рабочая схема с API модерации изображений короткая: загрузить в приватное хранилище, отправить URL на модерацию, принять решение по оценкам, затем опубликовать. С omni-moderation-latest помните, что на пиксели смотрят только шесть категорий, поэтому добавляйте в запрос подпись или OCR-текст, если вам важен текст внутри изображений, и держите отдельный механизм защиты детей. Начните с flagged, переходите к порогам по категориям, когда появятся размеченные данные, и перепроверяйте эти пороги при смене модели.

Чтобы попробовать, вставьте URL изображения в playground на странице модели Content Moderation, а затем перенесите пример на Python или JavaScript выше в свой бэкенд. В документации API перечислены все поля, которые принимает этот API модерации изображений.

Источники

1. OpenAI. Moderation. Получено в октябре 2026 г. с developers.openai.com/api/docs/guides/moderation
2. reAPI. omni-moderation-latest API docs. reapi.ai/docs/content-moderation
3. OpenAI. Moderations API reference. Получено в октябре 2026 г. с developers.openai.com/api/reference/resources/moderations
4. reAPI. Tasks API reference. reapi.ai/docs/api/tasks
5. Sightengine. Visual Moderation models. Получено в октябре 2026 г. с sightengine.com/docs/models
6. Sightengine. What are the ways to send an image to the API? Получено в октябре 2026 г. с sightengine.com/faq/ways-to-send-image-to-api
7. Sightengine. What is an operation? Получено в октябре 2026 г. с sightengine.com/faq/what-is-an-operation
8. Hive. Visual Moderation - Overview. Получено в октябре 2026 г. с docs.thehive.ai/docs/visual-content-moderation
9. Hive. Using Hive's Visual Moderation API. Получено в октябре 2026 г. с docs.thehive.ai/docs/visual-moderation-api
10. Microsoft. Image Operations - Analyze Image (REST API). Получено в октябре 2026 г. с learn.microsoft.com/en-us/rest/api/contentsafety/image-operations/analyze-image
11. Microsoft. Harm categories in Azure AI Content Safety. Получено в октябре 2026 г. с learn.microsoft.com/en-us/azure/ai-services/content-safety/concepts/harm-categories
12. Microsoft. Azure AI Content Safety pricing. Получено в октябре 2026 г. с azure.microsoft.com/en-us/pricing/details/content-safety
13. Amazon Web Services. Using the image and video moderation APIs. Получено в октябре 2026 г. с docs.aws.amazon.com/rekognition/latest/dg/moderation-api.html
14. Amazon Web Services. DetectModerationLabels. Получено в октябре 2026 г. с docs.aws.amazon.com/rekognition/latest/APIReference/API_DetectModerationLabels.html
15. Amazon Web Services. Amazon Rekognition pricing. Получено в октябре 2026 г. с aws.amazon.com/rekognition/pricing
16. OpenAI. Images and vision. Получено в октябре 2026 г. с developers.openai.com/api/docs/guides/images-vision