Requête simple POST /v1/responses

Leçon corrigée le 3 novembre 2026 d’après les bonnes pratiques et la référence de l’API xAI : la température est plafonnée à 1 et xAI recommande 0,7 avec top_p à 0,95 ; l’ancien exemple à 1,5 n’avait pas d’effet au-delà de 1. Source : Best practices.

Votre premier appel réussi

Vous avez votre compte, votre clé API et un SDK installé. Il est temps d’envoyer votre première requête à l’API Grok et de comprendre la structure de la réponse. Cette leçon se concentre sur l’endpoint principal /v1/responses, le plus moderne et le plus recommandé.

Structure de la requête

L’endpoint POST /v1/responses accepte au minimum deux paramètres :

• model : l’identifiant du modèle à utiliser
• input : le texte de votre requête (ou un tableau de contenus pour les cas avancés)

Requête minimale en Python

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1"
)

response = client.responses.create(
    model="grok-4.5",
    input="Quel est le langage de programmation le plus utilisé en 2026 ?"
)

print(response.output[0].content[0].text)

Avec des instructions système

Le paramètre instructions permet de définir le comportement du modèle :

response = client.responses.create(
    model="grok-4.5",
    instructions="Vous êtes un expert en développement web. Répondez de manière concise.",
    input="Quelle est la différence entre SSR et SSG ?"
)

Anatomie de la réponse

L’API retourne un objet JSON structuré. Voici les champs principaux :

{
  "id": "resp-abc123",
  "object": "response",
  "status": "completed",
  "model": "grok-4.5",
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "La réponse du modèle apparaît ici."
        }
      ],
      "status": "completed"
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 156,
    "total_tokens": 198
  }
}

Champs importants

• id : identifiant unique de la réponse, utile pour la récupérer plus tard
• status : completed si la génération est terminée
• output : tableau contenant les messages générés
• usage : compteurs de tokens pour suivre votre consommation

Paramètres optionnels courants

Contrôler la créativité

response = client.responses.create(
    model="grok-4.5",
    input="Proposez un nom pour une startup d'IA.",
    temperature=0.7,  # valeur recommandée par xAI
    top_p=0.95,
)

• L’API accepte une température de 0 à 2, mais ramène à 1 toute valeur supérieure
• xAI recommande temperature=0.7 et top_p=0.95, et déconseille de s’en écarter : la qualité baisse généralement
• Pour plus de créativité, demandez-la dans le prompt (« propose des noms inattendus »)

Limiter la longueur

response = client.responses.create(
    model="grok-4.5",
    input="Résumez le concept de machine learning.",
    max_output_tokens=200  # Limite la réponse
)

Activer le raisonnement

Pour les modèles de raisonnement, ajustez l’effort de réflexion :

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Résolvez ce problème : si 3x + 7 = 22, que vaut x ?",
    reasoning={"effort": "high"}
)

Les niveaux possibles sont low, medium et high.

Continuer une conversation

L’endpoint /v1/responses supporte les conversations multi-tours grâce au paramètre previous_response_id :

# Premier message
r1 = client.responses.create(
    model="grok-4.5",
    input="Je développe une API en Python."
)

# Deuxième message (le modèle se souvient du contexte)
r2 = client.responses.create(
    model="grok-4.5",
    input="Quel framework me recommandez-vous ?",
    previous_response_id=r1.id
)

Cette approche est plus simple que de gérer manuellement l’historique des messages.

Suivre les coûts

Le champ usage dans la réponse vous permet de calculer le coût de chaque appel. Le champ output_tokens_details.reasoning_tokens indique combien de tokens ont été utilisés pour le raisonnement interne du modèle (ces tokens sont facturés mais ne sont pas visibles dans la réponse).

Points clés à retenir

• L’endpoint POST /v1/responses est le plus moderne et le plus recommandé
• Deux paramètres obligatoires : model et input
• La réponse se trouve dans output[0].content[0].text
• Utilisez previous_response_id pour les conversations multi-tours
• Le champ usage vous aide à suivre votre consommation de tokens