Créer une réponse avec POST /v1/responses

Votre première requête

L’endpoint POST /v1/responses est le point d’entrée principal de la Responses API. C’est ici que vous envoyez vos prompts et recevez les réponses des modèles Grok. Dans cette leçon, vous allez apprendre à construire et envoyer votre première requête.

Authentification

Toutes les requêtes nécessitent un header d’authentification avec votre clé API xAI :

Authorization: Bearer $XAI_API_KEY

Vous pouvez générer vos clés sur console.x.ai. Gardez-les secrètes — ne les commitez jamais dans un dépôt Git.

Requête minimale

Voici la requête la plus simple possible :

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.20-reasoning",
    "input": "Explique-moi ce qu'est le machine learning en 3 phrases."
  }'

Deux champs suffisent :

• model : l’identifiant du modèle Grok à utiliser
• input : votre prompt, sous forme de texte simple

Avec le SDK Python

Si vous utilisez le SDK OpenAI (compatible xAI), la syntaxe est similaire :

from openai import OpenAI

client = OpenAI(
    api_key="xai-...",
    base_url="https://api.x.ai/v1"
)

response = client.responses.create(
    model="grok-4.20-reasoning",
    input="Explique-moi ce qu'est le machine learning en 3 phrases."
)

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

Input simple vs structuré

Le paramètre input accepte deux formats.

Texte simple

{
  "model": "grok-4.20-reasoning",
  "input": "Quelle est la capitale de la France ?"
}

Tableau structuré

Pour des entrées multimodales ou des rôles explicites :

{
  "model": "grok-4.20-reasoning",
  "input": [
    {
      "role": "user",
      "content": "Analyse cette image et décris ce que tu vois."
    }
  ]
}

Le format tableau vous donne plus de contrôle, notamment pour inclure des images ou spécifier des rôles différents.

Le paramètre instructions

Pour donner un comportement système au modèle, utilisez instructions plutôt que d’ajouter un message système dans input :

{
  "model": "grok-4.20-reasoning",
  "instructions": "Tu es un expert en cuisine française. Réponds toujours en incluant une astuce de chef.",
  "input": "Comment réussir une béchamel ?"
}

Le champ instructions est l’équivalent du system prompt dans Chat Completions. Il définit le comportement global du modèle pour toute la conversation.

Exercice pratique

Essayez de construire une requête qui :

1. Utilise le modèle grok-4.20-reasoning
2. Définit des instructions système pour un assistant technique
3. Pose une question sur Python

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.20-reasoning",
    "instructions": "Tu es un développeur Python senior. Donne des exemples de code concis.",
    "input": "Comment lire un fichier JSON en Python ?"
  }'

Points clés à retenir

• POST /v1/responses est l’endpoint principal — il nécessite model et input
• input accepte un texte simple ou un tableau structuré avec rôles
• instructions définit le comportement système du modèle
• L’authentification se fait via le header Authorization: Bearer
• Le SDK OpenAI est compatible avec xAI en changeant le base_url