Clé API Grok : obtention et configuration (2026)

L'intégration de l'API Grok n'est pas compliquée en soi. Trois points bloquent réellement les équipes : d'où vient la clé, comment écrire l'URL de base, et si la clé correspond bien à l'adresse utilisée. L'erreur 401 la plus fréquente ne vient pas d'une clé expirée, mais d'une clé d'une plateforme associée à l'adresse d'une autre.

Cet article suit l'ordre « voie d'obtention, création de la clé, configuration de l'adresse, appel minimal, sécurité et diagnostic ». Les noms de modèles et leur disponibilité sont ceux de la page Tarifs des modèles ; les libellés des menus de la console peuvent évoluer, référez-vous à la page réelle.

Remarque : xAI et Grok sont des marques de leurs détenteurs respectifs. Cet article est fourni à titre technique. Les interfaces, modèles et prix peuvent évoluer ; référez-vous à la documentation officielle de xAI et à la page Tarifs des modèles.

1. Confirmez d'abord le type de clé nécessaire

Une clé API Grok provient de deux sources courantes : la console officielle xAI et une passerelle IA locale proposant un point d'entrée compatible OpenAI. Les deux permettent d'appeler Grok, mais le compte, le paiement et le titulaire de facturation diffèrent.

Élément	Console officielle xAI	ZSQH AI Gateway
Public visé	Moyen de paiement international, accès stable	Paiement en Chine, facture en yuans
Système de compte	Compte xAI	Compte passerelle
Moyen de paiement	Moyens acceptés par la plateforme	Recharge en yuans
URL de base	`https://api.x.ai/v1`	`https://ai.zhongshangqihang.com/v1`
Facturation	Facture en dollars, taux de change à votre charge	Facture en yuans, usage multi-modèles unifié
Périmètre de modèles	Modèles de xAI	Plusieurs modèles activés sur la passerelle

Les clés des deux voies ne sont pas interchangeables. Une clé officielle ne fonctionne qu'avec l'adresse officielle ; une clé de passerelle qu'avec l'adresse de la passerelle. Choisissez la voie avant de créer la clé, sans mélanger ensuite.

2. Voie officielle xAI : obtenir une clé

Préparez un compte xAI utilisable et vérifiez son état, les conditions de service et les exigences régionales.
Connectez-vous à la console xAI et trouvez l'entrée de gestion des clés API. Les libellés de menu peuvent changer selon la version ; référez-vous à l'affichage réel.
Effectuez la configuration de facturation ou la recharge prépayée demandée par la console. Sans crédit disponible, une clé créée ne peut pas appeler correctement.
Créez une clé en incluant le projet et l'environnement dans son nom, par exemple prod-service-client, pour faciliter la rotation et l'audit.
Copiez et conservez la clé immédiatement après création. La plupart des plateformes ne l'affichent en entier qu'une fois.
Si la console propose des limites de quota, de droits ou d'IP, appliquez le principe du moindre privilège plutôt que d'ouvrir tous les droits par défaut.
Validez avec une requête minimale que la clé, l'adresse et le nom du modèle fonctionnent ensemble.

La voie officielle convient aux équipes qui n'utilisent que Grok et disposent d'un paiement et d'un accès international stables. Si le paiement ou le réseau est instable, la question passe de « le modèle est-il bon » à « peut-on appeler aujourd'hui », et le coût d'exploitation est souvent sous-estimé.

3. Passerelle : obtenir une clé

Ouvrez ZSQH AI Gateway, créez un compte et complétez les informations d'identité ou d'entreprise nécessaires.
Rechargez d'abord un petit montant pour valider le paiement, le crédit et le circuit d'appel, puis complétez le solde selon l'usage réel.
Créez une clé API dans la console, nommez-la par projet et fixez un plafond de consommation ou une alerte.
Notez l'URL de base de la passerelle : https://ai.zhongshangqihang.com/v1.
Envoyez une requête minimale avec la commande curl ci-dessous et vérifiez un code 200 avec du contenu.
Une fois le test réussi, intégrez le code métier et placez la clé dans les variables d'environnement du serveur.

L'intérêt de la passerelle ne se limite pas à « pouvoir accéder » : elle apporte aussi le paiement en yuans, une facturation unifiée, le changement de modèle et la gestion de plusieurs modèles avec une seule clé. Son adéquation dépend de votre moyen de paiement, de vos exigences de facturation et de votre périmètre d'exploitation.

4. Comment écrire l'URL de base et les points de terminaison

L'URL de base est l'endroit où l'on se trompe le plus facilement. Elle s'arrête généralement à /v1, et le SDK ajoute automatiquement le chemin suivant ; si vous écrivez l'adresse complète à la main, évitez de la concaténer deux fois.

Élément	xAI officiel	ZSQH AI Gateway
URL de base	`https://api.x.ai/v1`	`https://ai.zhongshangqihang.com/v1`
Point de terminaison Chat	`/chat/completions`	`/chat/completions`
En-tête d'authentification	`Authorization: Bearer <Key>`	`Authorization: Bearer <Key>`
Nom de modèle	Selon la liste officielle	Selon la page Tarifs des modèles

L'erreur classique consiste à écrire https://api.x.ai/v1/v1/chat/completions, ou à ajouter une barre oblique finale à l'URL de base puis à concaténer le chemin. Une autre erreur fréquente est d'utiliser l'en-tête x-api-key de style Anthropic avec Grok. Le point d'entrée compatible OpenAI de Grok utilise l'authentification Bearer.

5. Validation par un appel minimal

Commencez par curl pour écarter les problèmes liés au code. La commande suivante n'envoie qu'un message court ; un code 200 avec un champ choices indique que la clé, l'URL de base et le nom du modèle correspondent :

export GROK_API_KEY="sk-votre_cle"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $GROK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4",
    "messages": [{"role": "user", "content": "Réponds uniquement OK"}],
    "max_tokens": 16
  }'

Un projet Python peut réutiliser directement le SDK OpenAI en changeant seulement la clé et l'URL de base :

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GROK_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.chat.completions.create(
    model="grok-4",
    messages=[{"role": "user", "content": "Explique en trois phrases ce qu'est une passerelle API."}],
    max_tokens=256,
)
print(resp.choices[0].message.content)

N'écrivez pas le nom du modèle de mémoire. Les modèles activés varient selon le compte et la passerelle ; référez-vous à la page Tarifs des modèles ou à la liste de la console. Un nom erroné renvoie généralement 404 ou model not found, et non une erreur de clé.

6. Sécuriser la clé

Conservez la clé uniquement dans les variables d'environnement du serveur ou un service de gestion des secrets, jamais dans le dépôt de code.
N'intégrez pas la clé dans un bundle frontend, une requête navigateur ou un paquet mobile ; le frontend doit appeler votre propre backend.
Une clé par projet, avec séparation test/production, pour faciliter les quotas, la rotation et l'analyse d'usage.
Les journaux ne conservent que les premiers caractères ou un hachage de la clé, jamais la valeur complète.
En cas de départ d'un collaborateur, de fin de projet ou de suspicion de fuite, révoquez et recréez immédiatement la clé.
Surveillez régulièrement la courbe d'usage : en cas d'appels anormaux, suspendez d'abord la clé avant de modifier le code métier.

La conséquence typique d'une fuite de clé n'est pas seulement « quelqu'un dépense à votre place » : données, quotas et facturation deviennent simultanément incontrôlables. Traitez une clé comme un mot de passe de base de données ; beaucoup de problèmes peuvent ainsi être évités.

7. Erreurs de configuration courantes

Symptôme	Cause fréquente	Traitement
401	Clé et URL de base non appariées ; espace ou saut de ligne dans la clé	Vérifier l'origine et recopier la clé
404	Chemin concaténé deux fois ; point de terminaison erroné	URL de base jusqu'à `/v1`, point de terminaison `/chat/completions`
model not found	Nom mal orthographié ou modèle non activé	Copier le nom depuis la page de tarifs ou la console
429	Fréquence, concurrence ou tokens au-delà de la limite	Réduire la concurrence, réessayer avec un backoff
insufficient quota	Solde insuffisant ou plafond de clé atteint	Recharger et vérifier le quota de la clé
Délai dépassé	Liaison réseau, proxy ou sortie longue	Vérifier la sortie, fixer des délais de connexion et de lecture raisonnables

Lors du diagnostic, conservez d'abord l'identifiant de requête et le code de statut de la réponse, puis modifiez la requête. Sans code de statut ni identifiant, on ne peut que deviner.

Questions fréquentes

La clé et l'URL de base doivent-elles venir du même fournisseur ?

Oui. Une clé officielle s'utilise avec l'adresse officielle, une clé de passerelle avec l'adresse de la passerelle. Un mélange produit généralement 401, parfois 404 ou une erreur de droits.

Peut-on placer la clé dans un navigateur ?

Ce n'est pas recommandé. Le code navigateur est visible par l'utilisateur et la clé peut être facilement extraite. La bonne pratique est que le frontend appelle votre backend, qui conserve la clé et relaie les requêtes.

Une clé peut-elle appeler plusieurs modèles ?

En mode passerelle, généralement oui : il suffit de préciser le nom du modèle dans la requête, à condition que le compte y ait accès. Pour un compte officiel, la liste disponible fait foi dans la console officielle.

Que faire en cas de fuite de clé ?

Révoquez ou désactivez immédiatement la clé dans la console, créez-en une nouvelle pour la remplacer et vérifiez l'usage et la facturation récents. Ne vous contentez pas de modifier la chaîne dans le code en laissant l'ancienne clé active.

Pourquoi une clé fraîchement copiée renvoie-t-elle toujours 401 ?

Vérifiez d'abord la présence d'espaces, de sauts de ligne ou de guillemets superflus, puis l'appariement de l'URL de base. Si l'échec persiste, testez directement avec curl pour écarter la configuration du SDK et l'environnement proxy.

Pour aller plus loin

Si vous avez besoin d'un point d'entrée unique pour appeler Grok et d'autres modèles, créez d'abord une clé de test sur ZSQH AI Gateway, validez une requête minimale, puis intégrez le code métier. La disponibilité des modèles et les prix sont ceux de la page Tarifs des modèles.