La difficulté d'intégration de l'API Grok ne réside généralement pas dans l'écriture de la requête, mais dans trois points : la clé et l'adresse vont-elles ensemble, quel point de terminaison utiliser, et où copier le nom du modèle. Bien traités, le premier appel aboutit en quelques minutes ; mal traités, les symptômes les plus fréquents sont 401, 404 ou model not found.

Cet article suit la documentation officielle de xAI et parcourt dans l'ordre : compte et clé, URL de base, nom du modèle, curl, Python, streaming et appels de fonctions, diagnostic des erreurs et liste de migration. Les prix et les modèles disponibles évoluent : vérifiez la page Models officielle de xAI et la page Tarifs des modèles avant d'intégrer.

Remarque : xAI et Grok sont des marques de leurs détenteurs respectifs, OpenAI également. Cet article est purement technique.

1. Choisir d'abord la voie : console officielle ou passerelle compatible

Une clé API Grok provient généralement de deux sources : la console officielle xAI, ou une passerelle nationale offrant une entrée compatible OpenAI. Les formats de requête sont proches, mais les comptes, le paiement et l'URL de base diffèrent, et les clés ne sont pas interchangeables.

Élément xAI officiel Passerelle IA ZSQH
Console console.x.ai ai.zhongshangqihang.com
URL de base https://api.x.ai/v1 https://ai.zhongshangqihang.com/v1
Paiement Selon les moyens pris en charge officiellement Recharge en yuans, selon les conditions du site
Adaptation Accès stable et moyen de paiement international Accès depuis la Chine, facture unifiée, changement de modèles

Choisissez la voie avant de créer la clé. Placer une clé officielle sur l'adresse de la passerelle, ou l'inverse, produit généralement un 401. L'inscription à la passerelle se fait ici ; l'utilité d'une passerelle dépend de vos contraintes de réseau, de paiement et de facturation.

2. Créer une clé en six étapes

  1. Créez un compte et connectez-vous à la console. La voie officielle est console.x.ai ; la voie passerelle passe par la page d'inscription.
  2. Effectuez la configuration de facturation ou la recharge. Sans crédit disponible, la clé peut être créée mais les appels échouer.
  3. Accédez à la page API Keys, créez une clé et nommez-la clairement avec le projet et l'environnement, par exemple prod-qa-2026-10.
  4. Copiez immédiatement la clé complète dans une variable d'environnement serveur ou un gestionnaire de secrets. La plupart des consoles ne l'affichent qu'à la création.
  5. Fixez les quotas, les restrictions d'IP ou les droits d'équipe selon le principe du moindre privilège ; n'exigez pas des options absentes de la console.
  6. Validez avec une requête minimale que la clé, l'URL de base et le nom du modèle correspondent bien.

N'écrivez jamais la clé dans du code front-end, un dépôt Git ou une discussion. Créez des clés séparées pour test et production, afin qu'une rotation n'affecte pas toute l'activité.

3. URL de base et points de terminaison : s'arrêter à /v1

L'URL de base officielle est https://api.x.ai/v1. Deux points à retenir : l'URL de base s'arrête à /v1, n'y ajoutez pas /chat/completions vous-même ; le point de terminaison précis est déterminé par le SDK ou le chemin de la requête.

Actuellement, xAI recommande POST /v1/responses (Responses API). Le format compatible OpenAI POST /v1/chat/completions reste utilisable, mais il est désormais marqué legacy et les nouvelles fonctionnalités arrivent d'abord dans Responses API. Pour un nouveau projet, utilisez directement Responses API ; un code existant en Chat Completions peut continuer, à condition d'accepter qu'il ne soit plus la voie principale.

Requête curl minimale, avec l'authentification Authorization: Bearer :

export XAI_API_KEY="votre-cle"

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": "Explique en trois phrases ce qu est une passerelle API.",
    "store": false
  }'

store contrôle la conservation des requêtes et réponses côté serveur. La documentation officielle indique que Responses conserve par défaut pendant 30 jours ; pour des contenus sensibles, fixez explicitement store: false et vérifiez qu'une fois désactivé, previous_response_id ne permet plus de poursuivre la conversation.

4. Nom du modèle : copier l'ID, ne pas deviner

Le nom du modèle est un identifiant d'API, pas le nom commercial d'une page produit. La page Models officielle liste les identifiants disponibles, la longueur de contexte et le palier de facturation. Voici quelques exemples issus de la documentation d'octobre 2026, uniquement pour illustrer le format :

ID de modèle Contexte Usage courant
grok-4.7 500k Questions générales, code, agents
grok-4.3 1M Documents longs, conversations longues
grok-4.20-0309-reasoning 1M Tâches nécessitant un raisonnement explicite
grok-build-0.1 256k Workflows de code et de build

Les modèles apparaissent et disparaissent, et les noms portent parfois un suffixe de date. Avant la mise en production, copiez l'identifiant depuis la page Models officielle ou la page Tarifs des modèles, sans le réécrire de mémoire. Les modèles suffixés -reasoning produisent généralement un raisonnement visible, avec une latence et une structure de coût différentes : testez d'abord à faible volume.

5. Premier appel en Python

xAI fournit un SDK propre et prend aussi en charge le SDK OpenAI. Une équipe déjà équipée en OpenAI peut démarrer en changeant base_url et api_key :

import os
from openai import OpenAI

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

response = client.responses.create(
    model="grok-4.7",
    input="Explique en trois phrases ce qu est une passerelle API.",
    store=False,
)

print(response.output_text)

output_text est une propriété pratique du SDK, adaptée aux résultats purement textuels. Pour lire le raisonnement, les appels d'outils ou les citations, parcourez response.output et testez le champ type : ne supposez pas que le texte se trouve toujours à un index fixe.

6. Streaming et appels de fonctions

Le streaming utilise SSE : ajoutez "stream": true à la requête et le client lit les incréments par blocs. La documentation officielle rappelle que la génération par un modèle de raisonnement peut être longue ; en streaming, augmentez le délai d'attente du client pour éviter une fermeture prématurée de la connexion. Voici l'appel via le SDK OpenAI sur un point de terminaison compatible :

stream = client.chat.completions.create(
    model="grok-4.7",
    messages=[{"role": "user", "content": "Explique SSE en trois phrases."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Un appel de fonction se déroule en cinq étapes : définir le nom, la description et le schéma JSON de l'outil ; l'inclure dans la requête ; le modèle renvoie un function_call ; vous exécutez la fonction localement ; vous renvoyez le résultat au modèle pour continuer la génération. Dans Responses API, la définition d'outil est plate, avec les champs type: "function", name, description et parameters.

Deux détails sont souvent négligés : en streaming, les arguments d'un appel de fonction peuvent arriver d'un bloc plutôt qu'au fil de l'eau ; les outils de recherche côté serveur peuvent être facturés séparément à l'appel, selon la page tarifaire officielle. Plus les outils sont nombreux et leurs descriptions vagues, plus le modèle risque d'en choisir un par erreur : commencez par en limiter le nombre et préciser les paramètres.

7. Erreurs courantes : lire d'abord le code HTTP

Code Cause courante Traitement
401 Clé absente ou erronée, ou clé et URL de base incompatibles Vérifiez l'en-tête Authorization et la cohérence de l'adresse
403 Compte ou clé sans droit, ou restriction géographique et contractuelle Consultez les droits et l'état du compte dans la console
404 Chemin erroné ou modèle inexistant Vérifiez /v1/responses et l'identifiant du modèle
400 / 422 Format de champ incorrect dans le corps de la requête Comparez avec la référence API
429 Fréquence ou concurrence au-delà de la limite Reprise avec backoff exponentiel, réduire la concurrence
Délai dépassé Génération longue d'un modèle de raisonnement, réseau lent Augmenter le délai, passer en streaming, journaliser la durée

Un solde insuffisant ne se manifeste pas toujours par un 429 ; le code et le message exacts dépendent de la console et de la documentation officielle. Ordre de diagnostic conseillé : le code HTTP d'abord, le message d'erreur ensuite, le prompt en dernier. Aucun prompt, aussi bon soit-il, ne corrigera une URL de base erronée.

8. Liste de migration avant la mise en production

  1. Placer la clé dans une variable d'environnement serveur, en vérifiant qu'elle n'entre ni dans le bundle front-end ni dans les journaux.
  2. Fixer l'URL de base et interdire la construction manuelle des points de terminaison dans le code métier.
  3. Établir une table de correspondance des modèles : ancien modèle, nouveau modèle, contexte et palier de facturation.
  4. Utiliser /v1/responses pour les nouveaux projets ; pour les anciens en Chat Completions, marquer legacy et planifier la migration.
  5. Unifier la logique de délai, de reprise et d'annulation entre streaming et non-streaming.
  6. Prévoir un backoff exponentiel pour les 429 et les 5xx, sans reprise illimitée.
  7. Journaliser l'identifiant de requête, le modèle, les tokens et la latence, pour la comptabilité et le diagnostic.
  8. Déployer d'abord sur une fonction non critique, observer une semaine, puis généraliser.

Questions fréquentes

Quelle URL de base utiliser pour l'API Grok ?

L'URL officielle est https://api.x.ai/v1 ; pour une passerelle, utilisez l'adresse indiquée par sa console. Arrêtez-vous à /v1, sans point de terminaison précis.

Pourquoi le SDK OpenAI peut-il appeler Grok ?

xAI fournit une structure de requête compatible OpenAI, notamment pour Chat Completions ; Responses API est également accessible via responses.create du SDK OpenAI. Il suffit de pointer base_url vers xAI, mais le nom du modèle et certains paramètres suivent la documentation xAI.

L'API Grok et l'API OpenAI sont-elles identiques ?

Non. Ce sont des services de sociétés différentes, dont les interfaces sont seulement compatibles. Clés, facturation, modèles et politiques de données diffèrent et ne sont pas interchangeables.

Faut-il obligatoirement utiliser Responses API ?

C'est recommandé pour les nouveaux projets. Chat Completions est marqué legacy et les nouvelles capacités arrivent d'abord dans Responses API ; les systèmes existants peuvent planifier la migration selon son coût, sans basculer du jour au lendemain.

Comment intégrer plus stablement depuis la Chine ?

Identifiez d'abord s'il s'agit d'un problème de réseau, de paiement ou de conformité. Si seul l'accès et le règlement posent problème, une passerelle compatible OpenAI peut être évaluée ; si les données ne peuvent pas sortir du réseau interne, envisagez un déploiement privé ou une autre architecture. La décision dépend de vos contraintes réelles.

En résumé

L'intégration de l'API Grok tient en une phrase : choisir la bonne source de clé, arrêter l'URL de base à /v1, copier le nom du modèle depuis la page officielle et privilégier Responses API pour les nouveaux projets. Le streaming, les appels de fonctions et la gestion des erreurs ne sont que des détails ajoutés à cette chaîne principale.

Pour gérer plusieurs modèles et une facturation unifiée, commencez par la page d'inscription ; les modèles et la facturation exacte font foi sur la page Tarifs des modèles.

Pour aller plus loin :