Appeler l'API avec cURL

L’outil universel pour tester les API

cURL est un outil en ligne de commande disponible sur tous les systèmes d’exploitation. Il permet d’envoyer des requêtes HTTP sans installer de SDK ni écrire de programme. C’est l’outil idéal pour tester rapidement un endpoint, déboguer une requête ou automatiser des appels dans un script shell.

Votre première requête cURL

Voici comment envoyer une requête à l’API Grok avec cURL :

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4",
    "messages": [
      {"role": "user", "content": "Bonjour, présentez-vous en une phrase."}
    ]
  }'

Décomposition de la commande

• curl https://api.x.ai/v1/chat/completions : envoie une requête POST (implicite avec -d) vers l’endpoint
• -H "Authorization: Bearer $XAI_API_KEY" : ajoute l’en-tête d’authentification avec votre clé
• -H "Content-Type: application/json" : indique que le corps est du JSON
• -d '{...}' : le corps de la requête au format JSON

Utiliser l’endpoint /v1/responses

L’endpoint moderne /v1/responses offre une syntaxe plus concise :

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4",
    "input": "Expliquez-moi le machine learning en termes simples."
  }'

Notez que input remplace messages pour les requêtes simples. Vous pouvez passer une chaîne de caractères directement au lieu d’un tableau de messages.

Options cURL utiles

Formater la sortie JSON

La réponse brute est difficile à lire. Utilisez jq pour la formater :

curl -s https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4", "input": "Bonjour"}' | jq .

L’option -s (silent) supprime la barre de progression de cURL.

Extraire uniquement la réponse

Pour récupérer le texte de la réponse sans les métadonnées :

curl -s https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4",
    "messages": [{"role": "user", "content": "Bonjour"}]
  }' | jq -r '.choices[0].message.content'

Voir les en-têtes de réponse

Pour déboguer les rate limits ou les erreurs, ajoutez -i pour afficher les en-têtes HTTP :

curl -i https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4", "input": "Test"}'

Lire le corps depuis un fichier

Pour les requêtes complexes, stockez le JSON dans un fichier :

# requete.json
{
  "model": "grok-4",
  "messages": [
    {"role": "system", "content": "Vous êtes un traducteur."},
    {"role": "user", "content": "Traduisez en anglais : Bonjour le monde"}
  ],
  "temperature": 0.3
}

Puis référencez-le avec @ :

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @requete.json

Déboguer les erreurs courantes

• 401 Unauthorized : clé API invalide ou absente. Vérifiez echo $XAI_API_KEY
• 400 Bad Request : JSON mal formé. Validez votre JSON avec jq . < requete.json
• 429 Too Many Requests : limite de débit atteinte. Attendez quelques secondes
• 404 Not Found : vérifiez l’URL et le chemin de l’endpoint

Points clés à retenir

• cURL est parfait pour tester et déboguer sans écrire de code
• Authentifiez-vous avec -H "Authorization: Bearer $XAI_API_KEY"
• Utilisez jq pour formater et filtrer les réponses JSON
• Stockez les requêtes complexes dans des fichiers JSON séparés