Obtenir une clé API Mistral n'est pas long : créer un compte, ouvrir la console, cliquer une fois sur créer, et la clé apparaît. Ce qui pose réellement problème, c'est la configuration après l'obtention : à quel espace de travail la clé appartient-elle, à quels connecteurs donne-t-elle accès, où la stocker, quand la renouveler, et pourquoi un 401 persiste alors que la clé a bien été copiée.

Cet article suit l'ordre réel des opérations : création de la clé, permissions, variables d'environnement, rotation et diagnostic des 401, en expliquant la différence entre une clé officielle et une clé ZSQH AI Gateway.

Note : Mistral, Mistral AI et les noms de modèles associés sont des marques de Mistral AI. Cet article n'a aucune affiliation avec Mistral AI ; il s'appuie sur la documentation publique d'octobre 2026 et les pratiques courantes. Quotas, permissions et forme des produits peuvent évoluer ; la console officielle et la page tarifs des modèles font foi.

1. Distinguer : clé officielle et clé de passerelle ne se mélangent pas

Une clé API Mistral a deux origines courantes.

La première est une clé créée dans la console officielle Mistral, utilisée avec l'entrée officielle https://api.mistral.ai/v1. La seconde est une clé créée dans la console ZSQH AI Gateway, utilisée avec l'entrée https://ai.zhongshangqihang.com/v1.

Le format des deux clés peut se ressembler, mais leur appartenance est totalement différente. Une clé officielle ne correspond qu'à l'entrée officielle, une clé de passerelle qu'à l'entrée de la passerelle ; un mélange renvoie généralement 401. C'est le premier point à vérifier lors du diagnostic.

2. Créer un compte et ouvrir la console

Le processus officiel se déroule entièrement dans le navigateur :

  1. Ouvrir https://console.mistral.ai, créer un compte Mistral ou se connecter.
  2. Suivre les indications de la page, notamment la vérification e-mail, puis entrer dans la console Studio.
  3. À la première utilisation, la documentation officielle indique que l'accès API est activé par défaut, sans carte bancaire, mais avec des limites d'usage et de débit.
  4. Dans la navigation de gauche, ouvrir API Keys.
  5. Cliquer sur Create new key.
  6. Renseigner Name, choisir Expiration et Connector access scope.
  7. Cliquer à nouveau sur Create new key pour terminer.
  8. Copier immédiatement la clé complète dans un gestionnaire de mots de passe ou un service de secrets côté serveur.

Le point le plus important : la clé complète n'apparaît qu'une fois, dans la fenêtre de confirmation. Après fermeture, la console ne la réaffiche plus. Si vous ne l'avez pas enregistrée, il faut en créer une nouvelle et supprimer l'ancienne.

3. Les trois options de création

Name (nom) sert à distinguer les usages, sans effet sur les permissions. Inscrivez l'environnement et l'application, par exemple mistral-dev-chat, mistral-prod-batch. Un nom comme « test » ne permet pas, quelques mois plus tard, de savoir s'il faut supprimer la clé.

Expiration (date d'expiration) détermine la durée de validité. L'officiel permet aux administrateurs de définir une politique d'expiration ; si elle est désactivée, l'option « sans expiration » est disponible. En pratique, il est plus sûr de fixer une échéance claire aux clés métier, par exemple une rotation trimestrielle. N'activez pas « permanent » sur toutes les clés par simple commodité.

Connector access scope (portée des connecteurs) propose deux options :

  • Shared connectors only : accès uniquement aux connecteurs partagés avec l'espace de travail courant, pas aux connecteurs privés du créateur. L'officiel recommande cette option pour l'automatisation.
  • Private and shared connectors : accès aux connecteurs privés du créateur et aux connecteurs partagés. À choisir seulement si les connecteurs privés sont réellement nécessaires.

Après création, l'espace de travail, la portée des connecteurs et l'expiration ne sont pas modifiables directement. Il faut créer une clé de remplacement puis supprimer l'ancienne. Dix secondes de vérification à la création évitent une migration ultérieure.

4. Workspace et permissions : la clé n'est pas un passe-partout global

Une clé Mistral est liée à un espace de travail. Chaque clé est rattachée au Workspace choisi à la création ; quotas, limites de débit et périmètre de ressources du Workspace s'appliquent à cette clé. Autrement dit, la frontière de permissions dépend non seulement de la clé, mais aussi du Workspace qui la porte.

Un administrateur d'organisation peut consulter, créer, renouveler et supprimer les clés de chaque Workspace sur admin.mistral.ai/organization/api-keys, et définir une politique d'expiration au niveau de l'organisation. Un développeur ordinaire gère ses clés dans le menu utilisateur de Studio ou la page API Keys.

Le principe de sécurité est le moindre privilège : si l'application n'a besoin que de connecteurs partagés, ne choisissez pas les connecteurs privés ; si une clé métier dédiée suffit, ne réutilisez pas une clé administrateur. Une clé administrateur intégrée au code métier est ensuite très difficile à contenir.

5. Placer la clé dans une variable d'environnement

N'écrivez pas la clé dans le code source, le JavaScript frontend, le paquet mobile ou un dépôt public. La bonne pratique est une variable d'environnement côté serveur, ou un service de gestion des secrets injecté à l'exécution.

# macOS / Linux : valable uniquement pour la session de terminal en cours
export MISTRAL_API_KEY="votre-clé"

# Exemple de fichier .env à la racine du projet (ajouter .env au .gitignore)
MISTRAL_API_KEY=votre-clé

Lecture en Python :

import os

api_key = os.environ["MISTRAL_API_KEY"]

Sous Windows PowerShell, utilisez $env:MISTRAL_API_KEY="votre-clé". En production, préférez un Secrets Manager cloud, un Secret Kubernetes ou un service équivalent, plutôt qu'un fichier .env conservé durablement sur le serveur.

Ne copiez pas la clé avec des espaces ou des sauts de ligne ; ne journalisez que le préfixe ou une empreinte hachée ; faites passer les appels frontend par le backend, sans distribuer la clé au navigateur.

6. Rotation et révocation : dans l'ordre, sans supprimer l'ancienne clé d'abord

La rotation vise à faire reprendre le trafic par la nouvelle clé avant de retirer l'ancienne, pour éviter une interruption. Procédez ainsi :

  1. Créer une nouvelle clé dans le même Workspace, avec la date de rotation dans le nom.
  2. L'écrire dans le service de secrets ou les variables d'environnement de la plateforme de déploiement.
  3. Déployer le service et vérifier que les nouvelles instances ont bien lu la nouvelle clé.
  4. Valider la nouvelle clé avec une requête minimale, puis observer un temps le taux d'erreur et l'usage.
  5. Une fois certain qu'aucun trafic n'utilise l'ancienne clé, la supprimer dans la console.
  6. Contrôler l'usage et les logs récents pour détecter des appels anormaux.

En cas de fuite suspectée, inversez l'ordre : supprimez ou désactivez d'abord l'ancienne clé pour arrêter l'hémorragie, puis créez et déployez la nouvelle. La documentation officielle traite la suppression comme la révocation : la clé devient immédiatement invalide. N'« observez » pas pendant une fuite : chaque minute de justificatif exposé peut coûter de l'argent.

7. Diagnostic des 401 : identifier le type d'échec

Un 401 signifie un échec d'authentification, mais la cause n'est pas toujours « clé mal saisie ». Le tableau ci-dessous se lit dans l'ordre.

Symptôme Cause fréquente Traitement
401 Unauthorized Requête sans en-tête Authorization Ajouter Authorization: Bearer <Key>
401 Unauthorized Clé copiée incomplète, avec espace ou saut de ligne Recopier et vérifier les caractères invisibles
401 Unauthorized Clé expirée ou supprimée Vérifier l'état dans la console, créer si besoin
401 Unauthorized Clé officielle avec l'adresse de la passerelle, ou l'inverse Clé et URL de base doivent venir de la même plateforme
401 Unauthorized Requête envoyée sur un mauvais chemin Le chemin officiel de chat est /v1/chat/completions
403 Forbidden Le Workspace de la clé n'a pas les droits sur ce modèle ou cette ressource Vérifier Workspace, permissions de modèle et portée des connecteurs

Distinguez aussi les erreurs voisines : 402 concerne généralement la facturation (solde insuffisant, plafond atteint, échec de paiement) ; 403 est un manque de permissions, pas une clé invalide ; 429 signale une limite de débit et appelle un backoff, pas un changement de clé en boucle. Mélanger 401, 402, 403 et 429 allonge le diagnostic.

8. Connexion directe officielle ou passerelle ZSQH

Si vous n'utilisez que Mistral et que compte et moyen de paiement officiels fonctionnent, la connexion directe est un choix clair : console, documentation et facture au même endroit, frontière des problèmes simple.

Si vous devez appeler Mistral, Claude, GPT, Gemini et d'autres modèles dans un même projet, ou souhaitez recharger en yuan avec une facture unifiée, ZSQH AI Gateway réduit le coût de gestion. La passerelle fournit une entrée compatible OpenAI ; changer de modèle revient surtout à changer le champ model, avec clé et adresse remplacées ensemble. Modèles disponibles et facturation figurent sur la page tarifs des modèles ; un nouveau utilisateur peut créer un compte depuis la page d'inscription ou accéder directement à https://ai.zhongshangqihang.com.

Dans tous les cas, ne placez pas clé officielle et clé de passerelle dans la même variable d'environnement. Utilisez plutôt MISTRAL_API_KEY et ZSQH_API_KEY, avec un choix explicite selon l'entrée.

9. Sept contrôles avant la mise en production

  • La clé n'apparaît que côté serveur ; aucun paquet frontend, log ou dépôt ne contient la valeur complète.
  • Développement, préproduction et production utilisent des clés différentes, idéalement dans des Workspaces différents.
  • Chaque clé a un usage et une date d'expiration explicites.
  • La portée des connecteurs suit le moindre privilège ; une clé métier n'utilise pas les droits administrateur.
  • Le compte dispose d'alertes d'usage ou de plafonds de consommation pour détecter les appels anormaux.
  • Les logs ne conservent que le préfixe ou l'empreinte de la clé, jamais le justificatif complet.
  • Un processus de révocation et de rotation est défini en cas de départ, de perte d'appareil ou de fuite suspectée.

Questions fréquentes

Peut-on obtenir une clé API Mistral gratuitement ?

La documentation officielle indique qu'à la première utilisation l'accès API est activé par défaut, sans carte bancaire, mais que le mode Free comporte des limites d'usage et de débit. Les quotas et limites exacts sont ceux de la console officielle. Un usage durable ou à forte concurrence nécessite généralement une offre payante.

Peut-on réafficher la clé complète après création ?

Non. La clé complète n'apparaît qu'une fois dans la fenêtre de confirmation ; après fermeture, elle n'est plus accessible. Sans sauvegarde, il faut créer une nouvelle clé et supprimer l'ancienne. Enregistrez-la immédiatement dans un gestionnaire de mots de passe ou un service de secrets.

Une clé peut-elle être partagée entre plusieurs applications ?

Techniquement oui, mais ce n'est pas recommandé. Avec une clé commune à plusieurs applications et environnements, impossible de savoir qui appelle en cas de problème, ni de révoquer séparément. Mieux vaut séparer les clés par application et environnement, au minimum test et production.

Un 401 signifie-t-il toujours une clé erronée ?

Non. Une clé absente, mal formatée, expirée, supprimée ou un en-tête sans Bearer renvoient aussi 401 ; une clé et une URL de base de plateformes différentes également. Vérifiez d'abord l'état de la clé, puis l'adresse d'entrée, enfin l'en-tête de requête.

Une clé officielle peut-elle utiliser l'adresse de la passerelle ZSQH ?

Non. La clé officielle correspond uniquement à https://api.mistral.ai/v1, la clé de passerelle uniquement à https://ai.zhongshangqihang.com/v1. Lors d'un changement d'entrée, clé et URL de base doivent être remplacées ensemble, sinon l'appel renvoie généralement 401.

Lectures associées :