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

La API de Moderación de OpenAI

Lección 5 de 14 Actualizado el 3 de noviembre de 2026 Avanzado
En esta página
  1. Una herramienta de moderación integrada
  2. Qué devuelve la API
  3. Categorías detectadas
  4. Moderar ambos extremos de la canalización
  5. Lo que esta API no hace
  6. Puntos clave

Actualizado el 3 de noviembre de 2026 según la guía Moderation de OpenAI: se ha añadido la categoría illicit (y illicit/violent), que faltaba en la tabla, junto con las categorías aplicables a imágenes. Fuente: Moderation.

Una herramienta de moderación integrada

OpenAI ofrece una API de Moderación gratuita que analiza texto para detectar contenido potencialmente dañino. Esta es la primera línea de defensa que debes integrar en cualquier aplicación que utilice modelos de OpenAI, y no estás limitado solo a ese caso de uso: dado que acepta texto sin formato como entrada, también puedes emplearla para filtrar entradas destinadas a otros modelos. El hecho de que sea gratuita cambia la forma en que abordas el problema. Los compromisos habituales —¿debemos moderar cada solicitud o solo las sospechosas?— pierden peso, ya que el único coste restante es la latencia.

Qué devuelve la API

La llamada básica cabe en una línea; lo que exige atención es la respuesta. La API devuelve tres elementos distintos: un booleano flagged que refleja la decisión de OpenAI, la lista de categorías activadas y, lo más importante, puntuaciones continuas por categoría. Estas puntuaciones marcan la diferencia en producción, porque te permiten decidir dónde trazar tú mismo la línea en lugar de heredar un umbral diseñado para un uso genérico.

from openai import OpenAI

client = OpenAI()

def moderate_content(text: str) -> dict:
    """Analiza texto mediante la API de Moderación de OpenAI."""
    response = client.moderations.create(input=text)
    result = response.results[0]

    return {
        "blocked": result.flagged,
        "categories": {
            cat: flagged
            for cat, flagged in result.categories.__dict__.items()
            if flagged
        },
        "scores": {
            cat: round(score, 4)
            for cat, score in result.category_scores.__dict__.items()
            if score > 0.01
        },
    }

# Prueba con diferentes tipos de contenido
examples = [
    "How do I bake a chocolate cake?",
    "I will kill you if you don't answer me",
    "Explain how AES encryption works",
]

for text in examples:
    result = moderate_content(text)
    status = "BLOCKED" if result["blocked"] else "OK"
    print(f"{status} : {text[:50]}...")
    if result["categories"]:
        print(f"  Categories : {list(result['categories'].keys())}")

Los tres ejemplos de prueba no son aleatorios: el primero debería pasar, el segundo debería bloquearse y el tercero, una pregunta técnica perfectamente legítima, te muestra cómo se comporta tu canalización ante vocabulario de seguridad. Este es exactamente el tipo de solicitud que un equipo de ciberseguridad gestiona a diario.

Categorías detectadas

La API clasifica el contenido problemático a lo largo de varios ejes, cada uno correspondiente a un tipo distinto de daño.

Categoría Descripción
harassment Acoso, amenazas, intimidación
hate Discurso de odio basado en la identidad
illicit Consejos o instrucciones para cometer actos ilícitos
self-harm Autolesiones, suicidio
sexual Contenido sexual explícito
violence Violencia gráfica, amenazas

Cada categoría también tiene subcategorías (por ejemplo, harassment/threatening, illicit/violent, violence/graphic) para un filtrado más fino. Con omni-moderation-latest, solo self-harm y sus variantes, sexual y violence (con violence/graphic) se aplican también a imágenes; las demás categorías solo se aplican al texto. Esta granularidad te evita tener que hacer compromisos burdos: una plataforma de moderación de foros podría querer bloquear harassment/threatening mientras tolera el harassment simple, que cubre muchas disputas ordinarias.

Cuando necesitas procesar volumen —un análisis retrospectivo del historial de una conversación, por ejemplo—, la API acepta una lista y devuelve un resultado para cada elemento, evitando múltiples idas y vueltas de red.

def moderate_batch(messages: list[str]) -> list[dict]:
    """Modera varios mensajes en una única llamada."""
    response = client.moderations.create(input=messages)
    results = []
    for i, result in enumerate(response.results):
        results.append({
            "index": i,
            "text": messages[i][:50],
            "blocked": result.flagged,
            "max_score": max(
                score
                for score in result.category_scores.__dict__.values()
            ),
        })
    return results

Moderar ambos extremos de la canalización

Un error común es moderar solo las entradas. Esto se basa en una intuición falsa: si el mensaje entrante es aceptable, la respuesta también lo será. Sin embargo, un modelo puede producir contenido problemático a partir de una solicitud neutra, especialmente cuando se basa en documentos recuperados cuyo contenido nadie ha verificado. La clase siguiente aplica, por tanto, el mismo tratamiento en ambas direcciones, añadiendo un umbral personalizado que endurece la decisión predeterminada de la API.

class ModerationPipeline:
    """Canalización de moderación de entrada + salida para una aplicación LLM."""

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

    def moderate_input(self, message: str) -> tuple[bool, dict]:
        """Modera el mensaje ANTES de enviarlo al modelo."""
        result = self.client.moderations.create(input=message).results[0]
        scores = result.category_scores.__dict__
        high_categories = {
            cat: score for cat, score in scores.items() if score > self.threshold
        }
        blocked = result.flagged or bool(high_categories)
        return blocked, {"flagged_api": result.flagged, "custom_categories": high_categories}

    def moderate_output(self, response: str) -> tuple[bool, dict]:
        """Modera la respuesta del modelo ANTES de enviarla al usuario."""
        return self.moderate_input(response)

    def process_message(self, user_message: str, system_prompt: str) -> str:
        """Canalización completa: moderación de entrada, LLM, moderación de salida."""
        # Paso 1: moderar entrada
        input_blocked, details = self.moderate_input(user_message)
        if input_blocked:
            return "Your message cannot be processed. Please rephrase it."

        # Paso 2: llamar al modelo
        response = self.client.chat.completions.create(
            model="gpt-5.6-sol",
            messages=[
                {"role": "system", "content": system_prompt},
                {"role": "user", "content": user_message},
            ],
        )
        model_response = response.choices[0].message.content

        # Paso 3: moderar salida
        output_blocked, _ = self.moderate_output(model_response)
        if output_blocked:
            return "The response was filtered for non-compliance."

        return model_response

# Uso
pipeline = ModerationPipeline(custom_threshold=0.5)
response = pipeline.process_message(
    "How do I protect my application against SQL injections?",
    "You are an expert in defensive cybersecurity."
)
print(response)

Lo que esta API no hace

Su limitación más importante es también la más malentendida: no detecta inyección de prompts. Un mensaje educado que es perfectamente inofensivo desde la perspectiva del contenido, pero que pide al modelo que ignore sus instrucciones, pasará sin activar ninguna categoría. Esperar que proteja contra la manipulación es como instalar un detector de humo y esperar que detenga los robos.

Los falsos positivos son la segunda limitación, particularmente sensible en contextos de seguridad o médicos, donde describir una amenaza forma parte del trabajo. Se añade una llamada de red adicional a cada solicitud, lo cual importa cuando buscas respuestas en tiempo real. La detección sigue siendo más fiable en inglés que en otros idiomas, un punto ciego que los atacantes conocen perfectamente. Por último, las categorías y los umbrales evolucionan con las actualizaciones: un conjunto de calibración de hace seis meses merece una reverificación.

Estos límites dictan cómo usar la herramienta. Modera en ambas direcciones, ajusta los umbrales categoría por categoría en lugar de globalmente y combínala sistemáticamente con otras capas —detección de inyecciones, filtrado de lógica de negocio— que detallan las siguientes lecciones. Registra los resultados, porque observar tus propios falsos positivos es la forma de aprender dónde mover los controles deslizantes. Y planifica el caso en que la API no esté disponible: decide ahora, mientras las cosas están tranquilas, si tu aplicación debe bloquear por defecto o dejar pasar el tráfico, en lugar de descubrir ese comportamiento durante un incidente.

Puntos clave

  • La API de Moderación es gratuita, rápida y sencilla de integrar
  • Detecta contenido ofensivo, pero no inyecciones ni jailbreaks
  • La canalización entrada-modelo-salida debe moderarse en ambos extremos
  • Los umbrales predeterminados rara vez encajan: adáptalos a tu contexto
  • Es una capa más entre otras, nunca la única línea de defensa