API Responses : l'objet reasoning en détail

L’objet reasoning dans l’API Responses

L’API Responses de xAI offre un contrôle fin sur le raisonnement via l’objet reasoning. Ce paramètre n’est disponible que sur l’API Responses (pas sur Chat Completions) et permet de configurer trois aspects du raisonnement : l’effort, la génération de résumé et le format du résumé.

Structure complète de l’objet reasoning

{
  "model": "grok-4.20-reasoning",
  "input": "Votre question ici",
  "reasoning": {
    "effort": "medium",
    "generate_summary": true,
    "summary": "auto"
  }
}

effort

Contrôle la profondeur de réflexion du modèle. Trois valeurs possibles :

• low : réflexion minimale, adapté aux tâches simples
• medium : équilibre entre profondeur et rapidité
• high : réflexion maximale pour les problèmes complexes

Ce paramètre est l’équivalent Responses API du reasoning_effort de Chat Completions, mais avec une valeur medium supplémentaire.

generate_summary

Un booléen qui indique si le modèle doit produire un résumé de son raisonnement en plus de la réponse finale.

{
  "model": "grok-4.20-reasoning",
  "input": "Comparez les avantages du tri rapide et du tri fusion.",
  "reasoning": {
    "effort": "high",
    "generate_summary": true
  }
}

Quand generate_summary est à true, la réponse contient un élément supplémentaire avec un résumé concis du processus de raisonnement. Ce résumé est en clair (pas chiffré), ce qui le distingue du reasoning.encrypted_content.

summary

Contrôle le format du résumé généré. Pour l’instant, la seule valeur documentée est "auto", qui laisse le modèle choisir le format le plus adapté.

{
  "reasoning": {
    "effort": "high",
    "generate_summary": true,
    "summary": "auto"
  }
}

Différence entre résumé et raisonnement chiffré

Ces deux mécanismes sont complémentaires mais distincts :

Vous pouvez activer les deux simultanément pour obtenir à la fois un résumé lisible et le raisonnement chiffré complet :

response = client.responses.create(
    model="grok-4.20-reasoning",
    input="Démontrez l'infinité des nombres premiers.",
    reasoning={
        "effort": "high",
        "generate_summary": True,
        "summary": "auto"
    },
    include=["reasoning.encrypted_content"]
)

Combinaisons courantes

Usage minimal : effort seul

{
  "reasoning": {
    "effort": "low"
  }
}

Le modèle raisonne avec un effort minimal. Pas de résumé, pas de raisonnement chiffré retourné.

Usage intermédiaire : effort + résumé

{
  "reasoning": {
    "effort": "medium",
    "generate_summary": true,
    "summary": "auto"
  }
}

Le modèle raisonne et fournit un résumé lisible. Idéal pour les applications qui veulent montrer le processus de réflexion à l’utilisateur.

Usage complet : effort + résumé + chiffré

{
  "reasoning": {
    "effort": "high",
    "generate_summary": true,
    "summary": "auto"
  },
  "include": ["reasoning.encrypted_content"]
}

Configuration maximale : raisonnement approfondi, résumé lisible et contenu chiffré pour réutilisation. À réserver aux cas où vous avez besoin de tout.

Quand omettre l’objet reasoning

Si vous n’avez pas besoin de contrôler le raisonnement, vous pouvez simplement omettre le paramètre reasoning. Le modèle utilisera ses paramètres par défaut. Cela reste valide et le modèle raisonnera tout de même (puisque grok-4.20-reasoning est un modèle de raisonnement par nature).

Points clés à retenir

• L’objet reasoning n’est disponible que sur l’API Responses
• effort contrôle la profondeur (low, medium, high)
• generate_summary produit un résumé lisible du raisonnement (en clair)
• summary: "auto" laisse le modèle choisir le format du résumé
• Vous pouvez combiner résumé et raisonnement chiffré dans la même requête
• Omettre reasoning est valide : le modèle raisonne avec les paramètres par défaut