Ir al contenido principal
Español— Elegir un idioma
Menú

Moderación de contenido con la API

Lección 19 de 22 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Moderación de contenido con la API
  2. La API de Moderation
  3. Categorías de moderación
  4. Canalización completa de moderación
  5. Moderación por lotes
  6. Registro de moderación
  7. Puntos clave

Actualizado el 3 de noviembre de 2026 según la guía de Moderation de OpenAI: faltaban en la lista y el código las categorías illicit e illicit/violent para el modelo omni-moderation-latest. Fuente: Moderation.

Moderación de contenido con la API

La API de Moderation de OpenAI detecta automáticamente contenido inapropiado. Es una herramienta gratuita y esencial para cualquier aplicación que acepte contenido generado por usuarios. La lección anterior te mostró cómo escribir filtros personalizados; esta te proporciona un clasificador entrenado que detecta lo que las expresiones regulares nunca captarán: amenazas veladas, insultos indirectos y formulaciones implícitas.

La API de Moderation

La llamada es intencionadamente mínima: un modelo, un texto y un resultado que se reduce a un booleano. El campo flagged responde a la pregunta binaria «¿Este contenido infringe las políticas de uso?», mientras que categories detalla cuáles. Dado que este endpoint es gratuito, no hay razón económica para omitirlo, ni siquiera a volúmenes elevados.

from openai import OpenAI
client = OpenAI()

# La API de Moderation es GRATUITA
moderation = client.moderations.create(
    model="omni-moderation-latest",
    input="Hello, how are you?"
)

result = moderation.results[0]
print(f"Content flagged: {result.flagged}")
print(f"Categories: {result.categories}")

# Result:
# Content flagged: False
# Categories: Categories(harassment=False, hate=False, ...)

Categorías de moderación

Tras el booleano se oculta una cuadrícula de gran precisión. El modelo devuelve una decisión por categoría: acoso, acoso amenazante, odio, odio amenazante, instrucciones para actos ilícitos (con o sin violencia), autolesión con sus variantes (instrucciones e intención), contenido sexual, contenido sexual que involucra a menores, violencia y violencia gráfica; junto con una puntuación de confianza entre 0,0 y 1,0 para cada una.

Estas puntuaciones importan más que la decisión binaria cuando quieres calibrar tu política. Una plataforma de foros profesional podría querer bloquear a partir de 0,3 para acoso, mientras que un servicio de ficción podría aceptar 0,7 para violencia. La función siguiente expone ambos niveles de información: las categorías activadas realmente y las puntuaciones brutas para tus propios umbrales.

def analyze_moderation(text: str) -> dict:
    """Análisis detallado de moderación."""
    moderation = client.moderations.create(
        model="omni-moderation-latest",
        input=text
    )

    result = moderation.results[0]

    # Categorías disponibles
    categories = {
        "harassment": result.categories.harassment,
        "harassment_threatening": result.categories.harassment_threatening,
        "hate": result.categories.hate,
        "hate_threatening": result.categories.hate_threatening,
        "illicit": result.categories.illicit,
        "illicit_violent": result.categories.illicit_violent,
        "self_harm": result.categories.self_harm,
        "self_harm_instructions": result.categories.self_harm_instructions,
        "self_harm_intent": result.categories.self_harm_intent,
        "sexual": result.categories.sexual,
        "sexual_minors": result.categories.sexual_minors,
        "violence": result.categories.violence,
        "violence_graphic": result.categories.violence_graphic,
    }

    # Puntuaciones de confianza (0.0 a 1.0)
    scores = {
        "harassment": result.category_scores.harassment,
        "hate": result.category_scores.hate,
        "self_harm": result.category_scores.self_harm,
        "sexual": result.category_scores.sexual,
        "violence": result.category_scores.violence,
    }

    return {
        "flagged": result.flagged,
        "detected_categories": [k for k, v in categories.items() if v],
        "main_scores": {k: round(v, 4) for k, v in scores.items()},
    }

# Prueba
result = analyze_moderation("Hello everyone!")
print(f"Flagged: {result['flagged']}")
print(f"Scores: {result['main_scores']}")

Canalización completa de moderación

Moderación de entradas de usuario

Vamos a envolver esta llamada en un componente reutilizable. ContentModerator devuelve un par explícito —aceptable o no, con el motivo— en lugar de un objeto bruto que cada llamador tendría que reinterpretar. Traducir las categorías a un lenguaje claro importa: este es el vocabulario que aparecerá en tu interfaz y registros, y debe ser comprensible para el equipo de moderación humana que se haga cargo.

class ContentModerator:
    """Moderador de contenido para aplicaciones."""

    def __init__(self, custom_threshold: float = 0.5):
        self.client = OpenAI()
        self.threshold = custom_threshold

    def moderate(self, text: str) -> tuple[bool, dict]:
        """Modera texto. Devuelve (es_aceptable, detalles)."""
        moderation = self.client.moderations.create(
            model="omni-moderation-latest",
            input=text
        )

        result = moderation.results[0]

        if result.flagged:
            categories = []
            if result.categories.harassment:
                categories.append("harassment")
            if result.categories.hate:
                categories.append("hate speech")
            if result.categories.sexual:
                categories.append("sexual content")
            if result.categories.violence:
                categories.append("violence")
            if result.categories.self_harm:
                categories.append("self-harm")

            return False, {
                "reason": "Inappropriate content detected",
                "categories": categories
            }

        return True, {"reason": "Content acceptable"}

    def moderate_conversation(self, messages: list[str]) -> list[dict]:
        """Modera una lista de mensajes."""
        results = []
        for msg in messages:
            acceptable, details = self.moderate(msg)
            results.append({
                "message": msg[:50] + "..." if len(msg) > 50 else msg,
                "acceptable": acceptable,
                **details
            })
        return results

# Uso
moderator = ContentModerator()
acceptable, details = moderator.moderate("Hello, how can I help you?")
print(f"Acceptable: {acceptable}")
print(f"Details: {details}")

Integración en la canalización de la API

La moderación enmarca la llamada por ambos lados. Filtrar la entrada evita pagar por la generación de contenido que rechazarías de todos modos; filtrar la salida protege contra casos en los que el modelo, hábilmente provocado, produce algo inaceptable por sí mismo. Observa la diferencia en el tratamiento: para la entrada, puedes decir al usuario qué se ha detectado, ya que él lo ha escrito; para la salida, el mensaje permanece vago, porque detallarlo implicaría describir lo que el modelo acaba de producir.

def moderated_chatbot(user_input: str) -> str:
    """Chatbot con moderación de entradas Y salidas."""
    moderator = ContentModerator()

    # 1. Moderar entrada
    input_ok, input_details = moderator.moderate(user_input)
    if not input_ok:
        return (f"Your message was blocked: "
                f"{', '.join(input_details['categories'])}")

    # 2. Generar respuesta
    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions="Respond in a professional and safe manner.",
        input=user_input
    )

    # 3. Moderar salida
    output_ok, output_details = moderator.moderate(response.output_text)
    if not output_ok:
        return "I am unable to provide that response."

    return response.output_text

# Prueba
print(moderated_chatbot("What is the capital of France?"))

Moderación por lotes

Esta doble llamada añade latencia, lo cual es aceptable en una conversación pero se vuelve prohibitivo cuando necesitas procesar diez mil reseñas de clientes importadas desde un archivo. Para moderar grandes volúmenes con eficiencia, pasa un array directamente: la API procesa todos los textos en una única solicitud y devuelve los resultados en el mismo orden, lo que te permite reasociarlos por índice.

def moderate_batch(texts: list[str]) -> list[dict]:
    """Modera múltiples textos en una única solicitud."""
    results = []

    # La API acepta un array de entradas
    moderation = client.moderations.create(
        model="omni-moderation-latest",
        input=texts
    )

    for i, result in enumerate(moderation.results):
        results.append({
            "index": i,
            "text_preview": texts[i][:50],
            "flagged": result.flagged,
        })

    flagged_count = sum(1 for r in results if r["flagged"])
    print(f"Moderated {len(texts)} texts: {flagged_count} flagged")

    return results

# Uso
texts = [
    "Hello, how are you?",
    "Great product, I recommend it!",
    "Customer service is excellent.",
]
results = moderate_batch(texts)

Registro de moderación

Una decisión de moderación afecta a un usuario, y tarde o temprano necesitarás justificarla, ya sea ante un cliente que impugna un bloqueo o ante un regulador. Por tanto, registra sistemáticamente el veredicto, el ID de usuario, las puntuaciones y un extracto del texto. El nivel de registro distingue los dos casos: warning para contenido marcado, que merece revisión humana, e info para el resto, que alimenta tus estadísticas.

import json
import logging
from datetime import datetime

logger = logging.getLogger("moderation")

def moderate_with_log(text: str, user_id: str = "anonymous") -> bool:
    """Modera y registra el resultado para auditoría."""
    moderation = client.moderations.create(
        model="omni-moderation-latest",
        input=text
    )

    result = moderation.results[0]

    log_entry = {
        "timestamp": datetime.now().isoformat(),
        "user_id": user_id,
        "flagged": result.flagged,
        "text_preview": text[:100],
        "scores": {
            "harassment": round(result.category_scores.harassment, 4),
            "hate": round(result.category_scores.hate, 4),
            "violence": round(result.category_scores.violence, 4),
        }
    }

    if result.flagged:
        logger.warning(json.dumps(log_entry))
    else:
        logger.info(json.dumps(log_entry))

    return not result.flagged

# Uso
is_ok = moderate_with_log("Test message", user_id="user-123")

Una última advertencia antes de continuar: la moderación clasifica contenido; no entiende la intención. Un mensaje perfectamente educado que intente hacer jailbreak a tu asistente pasará todos estos filtros sin ser marcado ni una sola vez. Ese es el tema de la siguiente lección.

Puntos clave

  • La API de Moderation es gratuita: úsala de forma sistemática
  • Modera tanto las entradas (contenido del usuario) como las salidas (respuestas del modelo)
  • El modelo omni-moderation-latest cubre todas las categorías de contenido
  • Registra todas las decisiones de moderación para auditoría
  • Usa el procesamiento por lotes para moderar grandes volúmenes con eficiencia
  • La moderación complementa las instrucciones del sistema; no las sustituye