Qu'est-ce que le paramètre guidelines de l'API Grok ? Modération de contenu personnalisée, expliquée

xAI a ajouté un paramètre guidelines à l'API texte de Grok, vous permettant d'indiquer au modèle de modérer davantage certaines catégories de contenu lors de la génération. Si vous développez sur Grok et avez besoin d'un contrôle plus strict sur les sorties sensibles, il s'agit du premier contrôle de contenu intégré à la requête que xAI propose pour le texte. Voici exactement ce que fait le paramètre guidelines de l'API Grok, quelles catégories il couvre, comment le configurer, ainsi que les limites de requêtes et les erreurs à anticiper.

Ce que fait le paramètre guidelines

Le paramètre guidelines est un tableau que vous ajoutez à une requête de l'API texte Grok pour modifier la façon dont le modèle gère certaines catégories de contenu. Pour chaque catégorie que vous listez, vous choisissez un comportement renforcé ; Grok suit ensuite les directives lors de la rédaction de sa réponse, avec ses propres mots. La réponse a la même structure qu'une réponse normale — il n'y a pas d'enveloppe supplémentaire à analyser.

Deux points importants à retenir :

• C'est opt-in par catégorie. Toute catégorie que vous omettez conserve le comportement de modération par défaut du modèle, vous ne listez donc que les catégories que vous souhaitez réellement modifier.
• C'est par requête. Les directives s'appliquent uniquement à la requête qui les contient. Pour couvrir toute une conversation, vous les envoyez à chaque requête de cette conversation.

La fonctionnalité a été documentée dans les notes de version de l'API Grok en octobre et, selon l'annonce de xAI, est disponible pour tous les clients API.

Quelles catégories et comportements sont pris en charge

Chaque entrée dans guidelines comporte trois champs : type (toujours "policy"), une category, et le behavior souhaité. Actuellement, le seul comportement disponible est decline.

La documentation décrit ces comportements à un niveau général et précise que xAI peut en affiner les détails au fil du temps. En pratique : decline est un ajustement doux intégré à la réponse, et non un classificateur strict qui renvoie une erreur — Grok reformule sa propre réponse pour rester dans les limites de la catégorie spécifiée.

Comment configurer guidelines dans une requête

Vous passez guidelines sous forme de tableau de premier niveau. Dans l'API Responses, il se place aux côtés de vos autres paramètres ; dans Chat Completions, il se situe au même niveau que messages. Voici une requête qui définit violence et nsfw sur 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" }
    ]
  }'

Notes sur les SDK qui posent souvent problème :

• SDK Python OpenAI : le champ n'est pas défini, passez-le donc dans extra_body.
• SDK JavaScript OpenAI : envoyez guidelines avec vos autres paramètres de requête.
• SDK Python xAI : chat.create stocke les directives sur le chat, de sorte que chaque appel sample() les envoie automatiquement — vous n'avez pas besoin de les répéter.

Quelles API le prennent en charge — et lesquelles ne le font pas

guidelines est accepté dans Chat Completions, l'API Responses, et chat.create dans le SDK Python xAI. Il ne fonctionne pas dans certains cas, et l'API rejette ces requêtes avec un 400 avant l'exécution du modèle :

• Les modèles multi-agents, tels que grok-4.20-multi-agent.
• Les complétions différées.
• Une requête sans outils côté serveur ni pièces jointes qui définit également stop, ou définit n supérieur à 1.

Comme la vérification s'effectue en amont, une requête rejetée ne vous coûte aucune inférence de modèle — mais cela signifie que vous devez gérer ces erreurs dans votre code.

Erreurs à anticiper

L'API valide guidelines avant d'exécuter le modèle et renvoie une erreur si elle ne peut pas les appliquer :

Dans le SDK Python xAI, une catégorie ou un comportement inconnu lève une ValueError avant même l'envoi de la requête ; les autres erreurs sont renvoyées sous forme de statut gRPC INVALID_ARGUMENT.

Pourquoi c'est important pour les développeurs

Grok a historiquement été positionné comme un modèle plus permissif, et les appels à l'API texte ne disposaient auparavant d'aucun contrôle de modération intégré à la requête — vous adoptiez le comportement par défaut du modèle ou filtriez les sorties vous-même. Le paramètre guidelines représente une voie intermédiaire : un pilotage au niveau des catégories que vous déclarez en ligne, sans appel de modération séparé ni logique de seuil dans votre propre code.

Il est délibérément limité pour l'instant — trois catégories, un seul comportement (decline), texte uniquement. Pour un chatbot orienté client où vous ne pouvez pas risquer des sorties sexualisées ou graphiquement violentes, déclarer nsfw et violence en decline constitue un garde-fou en une ligne. Pour tout ce qui est plus strict ou plus auditable, vous aurez toujours besoin de vos propres vérifications de sortie, car decline reformule la réponse plutôt que de la bloquer strictement — et vous devez toujours gérer les rejets 400/422 mentionnés ci-dessus.

Créez des workflows IA modérés avec vos propres agents

Les contrôles de contenu comme le paramètre guidelines de Grok ne sont qu'un élément pour faire fonctionner l'IA en toute sécurité en production — la partie la plus difficile consiste à intégrer la sortie d'un modèle dans des tâches réelles, des approbations et des outils. Eigent est une application multi-agents open-source de type « Cowork » qui fait tourner une équipe IA localement, vous permettant de conserver vos prompts et données sensibles sur votre propre machine pendant que les agents gèrent le workflow avec des points de contrôle humains. Découvrez comment cela s'adapte à une équipe réduite dans gérer une entreprise individuelle avec des agents IA, ou téléchargez Eigent pour l'essayer.