Requête simple POST /v1/responses

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",
    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",
    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",
  "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",
    input="Proposez un nom pour une startup d'IA.",
    temperature=1.5  # Plus créatif (entre 0 et 2)
)

• temperature=0 : réponses déterministes et factuelles
• temperature=0.7 : bon équilibre (valeur par défaut)
• temperature=1.5+ : réponses plus créatives et variées

Limiter la longueur

response = client.responses.create(
    model="grok-4",
    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-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",
    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",
    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