¿Qué es el parámetro guidelines de la API de Grok? Moderación de contenido personalizada, explicada

xAI añadió un parámetro guidelines a la API de texto de Grok, que te permite indicarle al modelo que modere de forma más estricta categorías de contenido específicas mientras escribe. Si desarrollas sobre Grok y necesitas un mayor control sobre el contenido sensible generado, este es el primer control de contenido en la solicitud que xAI lanza para texto. A continuación te explicamos exactamente qué hace el parámetro guidelines de la API de Grok, qué categorías cubre, cómo configurarlo y los límites de solicitud y errores que debes tener en cuenta.

Qué hace el parámetro guidelines

El parámetro guidelines es un array que añades a una solicitud de la API de texto de Grok para cambiar cómo el modelo gestiona ciertas categorías de contenido. Para cada categoría que incluyas, eliges un comportamiento mejorado; Grok sigue entonces las directrices mientras escribe su respuesta, con sus propias palabras. La respuesta tiene la misma estructura que una respuesta normal — no hay ningún contenedor adicional que analizar.

Hay dos aspectos clave:

• Es de activación opcional por categoría. Cualquier categoría que omitas mantiene el comportamiento de moderación predeterminado del modelo, por lo que solo debes incluir las categorías que realmente deseas modificar.
• Se aplica por solicitud. Las directrices solo se aplican a la solicitud que las contiene. Para cubrir una conversación completa, debes enviarlas en cada solicitud de esa conversación.

La funcionalidad fue documentada en las notas de versión de la API de Grok en octubre y, según el anuncio de xAI, está disponible para todos los clientes de la API.

Qué categorías y comportamientos son compatibles

Cada entrada en guidelines tiene tres campos: type (siempre "policy"), una category y el behavior que deseas para ella. Actualmente el único comportamiento disponible es decline.

La documentación describe estos comportamientos a alto nivel y señala que xAI puede refinar los detalles con el tiempo. La conclusión práctica: decline es una orientación más suave dentro de la respuesta, no un clasificador estricto que devuelve un error — Grok reformula su propia respuesta para mantenerse dentro de la categoría indicada.

Cómo configurar guidelines en una solicitud

Pasas guidelines como un array de nivel superior. En la Responses API se sitúa junto a los demás parámetros; en Chat Completions va al mismo nivel que messages. Aquí tienes una solicitud que establece tanto violence como nsfw en decline:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": "Write a short story about a knight.",
    "guidelines": [
      { "type": "policy", "category": "violence", "behavior": "decline" },
      { "type": "policy", "category": "nsfw", "behavior": "decline" }
    ]
  }'

Notas sobre los SDK que suelen causar confusión:

• SDK de Python de OpenAI: el campo no está definido, por lo que debes pasarlo en extra_body.
• SDK de JavaScript de OpenAI: envía guidelines junto con los demás parámetros de la solicitud.
• SDK de Python de xAI: chat.create almacena las directrices en el chat, por lo que cada llamada a sample() las envía automáticamente — no necesitas repetirlas manualmente.

Qué APIs lo admiten y cuáles no

guidelines es aceptado en Chat Completions, la Responses API y chat.create en el SDK de Python de xAI. No funciona en algunos casos, y la API rechaza esas solicitudes con un error 400 antes de que el modelo se ejecute:

• Modelos multiagente, como grok-4.20-multi-agent.
• Completions diferidas (deferred completions).
• Una solicitud sin herramientas del lado del servidor ni archivos adjuntos que además establezca stop, o establezca n mayor que 1.

Dado que la verificación ocurre de antemano, una solicitud rechazada no consume inferencia del modelo — pero sí significa que debes capturar estos errores en el código.

Errores que debes esperar

La API valida guidelines antes de ejecutar el modelo y devuelve un error si no puede aplicarlas:

En el SDK de Python de xAI, una categoría o comportamiento desconocido genera un ValueError antes de que la solicitud se envíe; los demás errores se devuelven como un estado gRPC INVALID_ARGUMENT.

Por qué esto importa para los desarrolladores

Grok ha sido históricamente posicionado como un modelo más permisivo, y las llamadas a la API de texto anteriormente no contaban con controles de moderación en la solicitud — debías aceptar el comportamiento predeterminado del modelo o filtrar el resultado tú mismo. El parámetro guidelines es un punto intermedio: orientación a nivel de categoría que declaras de forma inline, sin llamadas de moderación separadas ni lógica de umbrales en tu propio código.

Es deliberadamente limitado por ahora — tres categorías, un comportamiento (decline), solo texto. Para un chatbot orientado al cliente donde no puedes arriesgarte a contenido sexualizado o con violencia gráfica, declarar nsfw y violence como decline es una salvaguarda de una sola línea. Para casos más estrictos o auditables, seguirás necesitando tus propias verificaciones de salida, ya que decline reformula la respuesta en lugar de bloquearla completamente — y debes seguir gestionando los rechazos 400/422 mencionados anteriormente.

Crea flujos de trabajo de IA moderados con tus propios agentes

Los controles de contenido como el parámetro guidelines de Grok son una pieza para ejecutar IA de forma segura en producción — la parte más difícil es conectar la salida de un modelo con tareas reales, aprobaciones y herramientas. Eigent es una aplicación multiagente de código abierto tipo "Cowork" que ejecuta una fuerza de trabajo de IA de forma local, para que puedas mantener los prompts y datos sensibles en tu propia máquina mientras los agentes gestionan el flujo de trabajo con puntos de control de supervisión humana. Descubre cómo encaja esto en un equipo reducido en cómo gestionar una empresa unipersonal con agentes de IA, o descarga Eigent para probarlo.