Tutorial de API de moderación de imágenes: ejemplo en Python y JavaScript

Una API de moderación de imágenes recibe una imagen, la puntúa frente a una lista de categorías de daño y le indica si debe publicarla, retenerla o bloquearla. El problema con un modelo de propósito general como omni-moderation-latest es que no todas las categorías que reporta analizan realmente la imagen: la documentación de OpenAI marca 6 de sus 13 categorías como "Text and images" y las otras 7 como "Text only"^[1]. Si envía una foto sin pie de foto, esas 7 categorías de solo texto devuelven 0 por diseño, no porque la foto esté limpia^[1].

Esta guía explica qué significa eso en la práctica: en qué categorías puede confiar para imágenes, cómo enviar una imagen (reAPI solo acepta URL públicas), cómo se cobra una solicitud, cómo convertir las puntuaciones en decisiones, y un ejemplo ejecutable en Python y JavaScript que envía una imagen y consulta el resultado hasta obtener el veredicto. Termina con las diferencias frente a servicios especializados en imágenes como Sightengine, Hive, Azure AI Content Safety y Amazon Rekognition.

TL;DR

• omni-moderation-latest puntúa imágenes en 6 categorías: sexual, self-harm, self-harm/intent, self-harm/instructions, violence y violence/graphic. Las otras 7, incluida sexual/minors, son solo de texto^[1].
• En reAPI, una imagen entra como bloque image_url con una URL http(s) pública. Base64 y las URI data: se rechazan^[2].
• El cobro es por unidad de moderación: una unidad por imagen, una por cada 1,000 palabras de texto y al menos una unidad por solicitud^[2]. Las tarifas vigentes están en la página del modelo.
• La llamada es asíncrona: POST /api/v1/moderations y luego consulte GET /api/v1/tasks/{id} hasta que status sea completed^[2].
• flagged es el veredicto por defecto del modelo. Para su propia política, aplique umbrales a category_scores (de 0 a 1) por categoría y recalíbrelos cuando el modelo se actualice^[1].
• Si el endpoint propio de OpenAI es gratuito se trata en ¿Es gratis la API de moderación de OpenAI?.

Qué categorías de daño puede ver una API de moderación de imágenes

OpenAI indica qué entradas admite cada categoría de omni-moderation-latest^[1]:

Hay dos consecuencias importantes para un pipeline de imágenes.

Primera: un cero no siempre es una medición. OpenAI afirma que si envía solo imágenes, sin texto que las acompañe, el modelo devuelve una puntuación de 0 en las categorías de solo texto^[1]. Un símbolo de odio en un meme o una amenaza escrita dentro de una captura de pantalla no los detectará la puntuación de hate o harassment de una solicitud que solo contiene la imagen. La respuesta le indica en category_applied_input_types frente a qué tipos de entrada se evaluó cada categoría; en el ejemplo de OpenAI con solo imagen, las seis categorías de imagen muestran ["image"] y el resto un array vacío^[1]. Revise ese campo antes de tratar una puntuación baja como un aprobado.

Segunda: sexual/minors es solo de texto^[1]. La guía de OpenAI también indica que no se envíe a la Moderation API material de abuso sexual infantil conocido o sospechoso, porque no está diseñada para detectar CSAM y no sustituye a las salvaguardas dedicadas a la protección infantil^[1]. Si su plataforma acepta subidas de usuarios, prevea un control de protección infantil aparte.

OpenAI documenta un límite de 20 MB por archivo de imagen para el modelo^[1].

Envío de imágenes: solo URL públicas

El cuerpo de la solicitud tiene un único campo de contenido, input. Para imágenes se envía un array de bloques de contenido^[2]:

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

La propia referencia de la API de OpenAI dice que image_url.url puede ser una URL de imagen o datos de imagen codificados en base64^[3]. reAPI solo acepta la primera forma: image_url.url debe ser una URL http(s) pública, y las URI base64 o data: no pasan la validación y devuelven el error 20003^[2]. Esa regla se aplica a las entradas multimedia de todos los modelos de reAPI.

Para las subidas de usuarios, esto implica el siguiente orden: guardar el archivo, obtener una URL que se pueda descargar desde internet y después moderar. Las URL firmadas funcionan siempre que sigan siendo válidas cuando se ejecute la tarea^[2]. Si la URL no se puede descargar, la tarea falla con 80007 y el cargo se reembolsa^[2]. Mantenga el objeto privado y sin publicar hasta que llegue el veredicto.

También puede poner un pie de foto y su foto en el mismo array. La documentación de reAPI señala que un array de bloques de contenido devuelve un solo resultado para todo el conjunto, de modo que el modelo juzga el texto y la imagen juntos^[2]. Eso es lo que conviene para una publicación con pie de foto. No es lo que conviene para diez subidas sin relación entre sí: un veredicto combinado no le dirá qué imagen lo provocó, así que envíelas en solicitudes separadas.

Cómo se cobra la moderación de imágenes

reAPI cobra omni-moderation-latest por unidad de moderación^[2]:

Las unidades se convierten a créditos una vez por solicitud y se redondean hacia arriba, la consulta de estado es gratuita y las solicitudes fallidas se reembolsan automáticamente^[2]. Una solicitud admite hasta 500 elementos^[2]. La tarifa por unidad está en la página del modelo. Para una comparación de precios y niveles gratuitos entre proveedores, consulte ¿Es gratis la API de moderación de OpenAI?.

Ejemplo de API de moderación de imágenes en Python y JavaScript

Ambos ejemplos hacen lo mismo: envían una imagen, consultan la tarea cada 3 segundos y devuelven el primer resultado. La documentación de tareas de reAPI recomienda no consultar más a menudo que cada 2 o 3 segundos, porque el endpoint de consulta se almacena en caché durante 5 segundos mientras la tarea está en curso^[4]. Una comprobación de moderación suele terminar en pocos segundos^[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+, guardado como módulo .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);

Ejecute la versión de JavaScript en su servidor, no en el navegador. La API key es un token Bearer, y meterla en el código del front-end la expone a cualquiera que abra las herramientas de desarrollo. Lo mismo vale para la pregunta sobre React de las preguntas frecuentes más abajo. El esquema completo de la solicitud, incluidas las entradas de texto y mixtas, está en la documentación de la API.

Cómo leer el resultado y fijar umbrales

Cada resultado contiene cuatro campos^[1][2]:

flagged es un primer filtro razonable, pero refleja los valores por defecto del modelo, que pueden ser más estrictos o más laxos que su política^[2]. La recomendación de OpenAI es tratar las puntuaciones como señales para la política de su aplicación y no como una decisión de bloqueo automática, y enviar el contenido marcado a revisión cuando sea necesario^[1].

Un esquema habitual son tres franjas por categoría de imagen: permitir por debajo de una puntuación baja, enviar a revisión humana en la zona intermedia y bloquear por encima de una puntuación alta. Una versión mínima:

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"

Las cifras de arriba son ilustrativas, no recomendaciones. Elija las suyas pasando unos cientos de imágenes que ya haya etiquetado y observando dónde caen las puntuaciones. Repita esa comprobación periódicamente: OpenAI dice que planea seguir mejorando el modelo subyacente y que las políticas personalizadas basadas en category_scores pueden necesitar recalibrarse con el tiempo^[1]. reAPI no redondea ni reasigna las puntuaciones al pasarlas^[2], así que una calibración que haga una vez se aplica directamente a los valores que lee su código.

En qué se diferencian las API de moderación especializadas en imágenes

Un modelo general y un servicio especializado en imágenes responden a preguntas distintas. omni-moderation-latest puntúa seis categorías visuales y puede juzgar un pie de foto y su imagen juntos^[1]. Las API especializadas en imágenes detectan muchas más clases visuales, como armas, drogas, símbolos de odio o texto dentro de la imagen, y difieren en cómo reciben el archivo y cómo reportan la confianza. Según la documentación de cada proveedor:

Tres diferencias suelen decidir la elección.

Cobertura visual. Si necesita detectar armas, drogas, símbolos de odio o texto incrustado en una imagen, los servicios especializados enumeran esas clases de forma explícita^[5][8][13]. omni-moderation-latest no tiene categorías de imagen para ellas^[1].

Forma de la puntuación. Hive devuelve una confianza de 0–1 por clase y sugiere empezar en torno a 0.90 para marcar una clase^[8]. Rekognition descarta las etiquetas por debajo de MinConfidence, que por defecto es 50 en una escala de 0–100^[14]. Azure devuelve niveles de severidad gruesos para imágenes: 0, 2, 4 o 6^[11]. Un umbral ajustado en un servicio no se traslada a otro.

Manejo de la entrada. Azure y Rekognition aceptan bytes en base64^[10][14], y Sightengine y Hive aceptan la subida directa de un archivo^[6][9]. reAPI solo acepta URL^[2], lo que encaja con pipelines en los que la subida ya termina en un almacenamiento de objetos.

omni-moderation-latest encaja cuando su contenido es sobre todo texto con imágenes adjuntas, cuando las seis categorías visuales coinciden con su política o cuando ya llama a otros modelos a través de reAPI con la misma key. Para una comparación más amplia por modalidad y caso de uso, consulte La mejor API de moderación de contenido.

Preguntas frecuentes

API de moderación de imágenes gratis

OpenAI afirma que su propio endpoint de moderación es de uso gratuito^[1]. En reAPI, omni-moderation-latest es de pago por uso a una unidad por imagen, y las solicitudes fallidas se reembolsan^[2]. Los niveles gratuitos y los límites de tasa de cada proveedor se comparan en ¿Es gratis la API de moderación de OpenAI?.

API gratis para moderar imágenes subidas

Moderar una subida es un flujo de tres pasos: guardar el archivo de forma privada, crear una URL que la API pueda descargar (una URL firmada sirve mientras sea válida) y después enviar esa URL y publicar solo tras el veredicto^[2]. reAPI no acepta directamente los bytes del archivo ni una cadena base64^[2]. Para saber qué servicios tienen un cupo gratuito, consulte ¿Es gratis la API de moderación de OpenAI?.

API de moderación de imágenes de OpenAI

Sí, el modelo de moderación de OpenAI admite imágenes. omni-moderation-latest acepta entradas de texto e imagen, no clasifica audio y puntúa las imágenes solo en las categorías de contenido sexual, autolesiones y violencia^[1]. El ID del modelo en reAPI es el mismo, omni-moderation-latest, detrás de un endpoint de tareas asíncronas^[2].

API de moderación de imágenes Python

El ejemplo de Python de arriba está completo: envía un bloque image_url a /api/v1/moderations, consulta /api/v1/tasks/{id} y devuelve output.moderation.results[0]. Solo necesita el paquete requests. La documentación de la API muestra la misma llamada en cURL, Node.js y Go.

API de moderación de imágenes React

Llame a la API de moderación desde su backend, no desde un componente de React. Su app de React sube el archivo a su servidor o almacenamiento, su servidor llama a la API con la key y el cliente solo recibe la decisión. Poner la key Bearer en el código del navegador la expone a cada visitante.

¿Puede la ChatGPT API analizar imágenes?

Sí. Los modelos de OpenAI con visión analizan imágenes a través de la Responses API y la Chat Completions API, a partir de una URL, una data URL en base64 o un ID de archivo^[16]. Eso es comprensión de imágenes abierta. Para un conjunto fijo de categorías de daño con puntuaciones de 0–1, el endpoint de moderación es la opción diseñada para ello^[1].

Mejor API de moderación de imágenes

Depende de lo que necesite detectar. Un modelo general como omni-moderation-latest cubre contenido sexual, autolesiones y violencia en imágenes y añade categorías de texto para los pies de foto^[1]; los servicios especializados en imágenes cubren más clases visuales (vea la tabla de arriba). La guía de selección completa está en La mejor API de moderación de contenido.

Cómo integrar la moderación de imágenes en un flujo de subida

Montar una API de moderación de imágenes que funcione lleva pocos pasos: subir a un almacenamiento privado, moderar la URL, actuar según las puntuaciones y después publicar. Con omni-moderation-latest, recuerde que solo seis categorías miran los píxeles, así que añada a la solicitud un pie de foto o texto de OCR si le importa el texto dentro de las imágenes, y mantenga un control aparte para la protección infantil. Empiece con flagged, pase a umbrales por categoría cuando tenga datos etiquetados y revise esos umbrales cuando cambie el modelo.

Para probarla, pegue una URL de imagen en el playground de la página del modelo Content Moderation y luego pase el ejemplo de Python o JavaScript de arriba a su backend. La documentación de la API enumera todos los campos que acepta esta API de moderación de imágenes.

Referencias

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