Une clé API GLM est l'identifiant qui permet d'appeler les modèles GLM de Zhipu. Elle ressemble à une simple chaîne de caractères, mais elle détermine trois choses : si une requête passe l'authentification, sur quel compte les coûts sont imputés, et l'ampleur du risque en cas de fuite. Beaucoup d'échecs d'intégration ne viennent ni du modèle ni du réseau : la clé est du mauvais type, mal stockée, ou n'a jamais été renouvelée depuis sa création.
Cet article suit l'ordre « choisir le type, créer, conserver, renouveler, dépanner » et présente les deux voies d'obtention : la plateforme officielle et la passerelle ZSQH AI Gateway. Il se termine par une liste de configuration sécurisée directement applicable.
Remarque : Zhipu, GLM et BigModel sont des marques de leurs détenteurs respectifs. Cet article est fourni à titre technique et n'implique aucune affiliation, représentation ni autorisation de Zhipu. L'entrée de création des clés, les exigences d'authentification et les règles de facturation font foi dans la documentation officielle de la plateforme ouverte Zhipu.
1. Distinguez d'abord le type de clé dont vous avez besoin
La plateforme ouverte Zhipu gère séparément les clés des offres individuelles, des offres d'équipe et de l'API standard des modèles ; elles ne sont pas interchangeables. Avant de créer une clé, confirmez son usage, faute de quoi vous risquez le scénario classique : « la clé est valide, mais l'appel échoue ».
- Clé API standard : destinée aux services backend, scripts, agents et traitements par lots, facturée selon le volume réel d'appels. La grande majorité des intégrations techniques relève de cette catégorie.
- Clé Coding Plan : destinée aux outils de programmation comme Claude Code ; elle relève des avantages de l'abonnement et ne convient pas aux interfaces métier génériques.
- Clés d'équipe ou d'entreprise : destinées au travail collaboratif et à l'administration centralisée ; les droits et le rattachement de facturation diffèrent des clés individuelles.
Utiliser une clé Coding Plan sur l'API standard produit souvent un échec d'authentification ou un message indiquant que l'offre ne donne pas accès à ce modèle. Face à ce type d'erreur, vérifiez d'abord le type de produit de la clé, puis si la clé a été copiée en entier.
2. Créer une clé sur la plateforme ouverte Zhipu
La voie officielle convient aux équipes qui utilisent uniquement GLM et souhaitent accéder immédiatement aux nouveaux modèles et fonctionnalités. Les étapes principales sont les suivantes :
- Ouvrez la plateforme ouverte Zhipu, créez un compte et connectez-vous.
- Rendez-vous dans la page API Keys de la console et vérifiez le projet ou l'espace courant.
- Cliquez sur la création d'une clé et nommez-la selon le schéma « environnement-service », par exemple
prod-service-client. - Copiez la clé complète et stockez-la immédiatement dans un gestionnaire de mots de passe ou dans le système de gestion des secrets du serveur.
- Vérifiez le solde ou l'état du pack de ressources dans la page financière, afin d'éviter une clé créée mais inutilisable.
- Validez la clé avec une requête minimale avant de l'inscrire dans la configuration de production.
Deux points d'attention : la clé n'est généralement affichée en entier qu'au moment de sa création et peut ne plus être consultable après fermeture de la page ; les exigences de vérification d'identité ou d'entreprise évoluent selon les produits et les politiques, et font foi dans les indications de la page et la documentation officielle.
3. Créer une clé via la passerelle
Si votre équipe utilise plusieurs modèles en parallèle, ou souhaite unifier les quotas, la facturation et les factures, vous pouvez créer un compte sur ZSQH AI Gateway. Dans la page des clés API, créez une clé, fixez un plafond de quota et une date d'expiration, puis consultez la page Tarifs des modèles pour confirmer les modèles GLM disponibles et leur mode de facturation.
Une clé de passerelle n'est valide que sous l'URL de base de ZSQH ; elle ne peut pas être utilisée pour appeler l'adresse officielle de Zhipu, et inversement une clé officielle ne fonctionne pas directement sur la passerelle. Le plus simple est de nommer et de stocker séparément les deux jeux de clés.
4. Placer la clé dans des variables d'environnement
La pratique la plus dangereuse consiste à écrire la clé dans le code source, dans un bundle frontend ou dans l'historique d'une messagerie. Privilégiez les variables d'environnement ou un service de gestion des secrets, afin que le code ne référence que le nom de la variable.
# .env reste en local et doit figurer dans .gitignore
GLM_API_KEY=your_key_here
GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("GLM_API_KEY"),
base_url=os.getenv("GLM_BASE_URL"),
)
En pratique, appliquez au minimum ces règles : ne jamais versionner .env dans Git ; utiliser le Secret Manager du fournisseur cloud, un KMS ou les secrets de la plateforme d'orchestration en production ; recourir à des variables chiffrées dédiées en CI/CD ; masquer l'en-tête Authorization dans les journaux ; ne jamais faire apparaître une clé côté serveur dans le code frontend.
5. Isolation des droits, rotation et audit
Une seule clé pour tout faire paraît simple à court terme, mais complique le diagnostic sur la durée. Voici comment découper les usages.
| Pratique | Problème résolu | Mise en œuvre |
|---|---|---|
| Séparer test et production | Trafic de test facturé à tort, suppressions accidentelles | Deux clés, deux quotas |
| Une clé par service | Impossible d'identifier la source des appels | Nommer par service ou par dépôt |
| Fixer un plafond de quota | Consommation rapide en cas d'anomalie | Configurer limites et alertes dans la console |
| Renouveler régulièrement | Risque de fuite prolongée | Rotation trimestrielle, révocation immédiate au départ d'un collaborateur |
| Conserver les journaux d'appels | Litiges et retours d'incident | Enregistrer date, modèle et volume, jamais la clé en clair |
Lors d'une rotation, ne supprimez pas directement l'ancienne clé. Créez d'abord la nouvelle, basculez le trafic progressivement, vérifiez que les quotas, les droits sur les modèles et la facturation sont corrects, puis révoquez l'ancienne. Ainsi, un problème de configuration reste réversible rapidement.
6. Erreurs 401 et autres erreurs courantes
Un code HTTP 401 signifie seulement que l'authentification a échoué ; la cause précise se lit dans le code métier du corps de réponse. Dans les codes d'erreur officiels de Zhipu, 1000 indique un échec de vérification d'identité, 1001 une information d'authentification absente de l'en-tête, 1003 un jeton expiré et 1005 un compte soumis à une double authentification. Procédez dans cet ordre :
- Vérifiez que l'en-tête est
Authorization: Bearer <key>, sans espace ni guillemet superflu. - Vérifiez que la clé copiée est complète et que vous n'avez pas pris le nom ou le masque pour la clé.
- Vérifiez que le type de clé correspond à l'interface ; ne mélangez pas clé API standard et clé d'abonnement.
- Vérifiez que l'URL de base correspond à l'origine de la clé : clé officielle avec adresse officielle, clé de passerelle avec adresse de passerelle.
- Vérifiez l'état du compte : un impayé renvoie 1113, une limitation de débit renvoie 1302 ou 1305.
Par ailleurs, 1211 signale un modèle inexistant, souvent à cause d'un nom mal orthographié ou d'un modèle non activé ; 1261 signale une entrée trop longue, qui nécessite de compresser le contexte ou de découper la requête. Journaliser les codes métier accélère considérablement le diagnostic.
7. Liste de vérification avant mise en production
- La clé n'existe que côté serveur ou dans un service de gestion des secrets.
- Les environnements de test, de production et de CI utilisent des clés différentes.
- Chaque clé possède un plafond de quota et un responsable identifié.
- Des alertes sont configurées pour le solde insuffisant et les pics d'usage.
- Une révocation et un remplacement de clé ont déjà été testés.
- Les journaux ne contiennent ni clé complète ni données sensibles comme les numéros de téléphone.
- Les clés liées à un collaborateur parti ou à une passation ont été récupérées.
8. Questions fréquentes (FAQ)
1. Où créer une clé API GLM ?
Après connexion à la plateforme ouverte Zhipu, dans la page API Keys de la console. Si vous utilisez ZSQH AI Gateway, créez-la dans la page des clés API de la console de la passerelle ; les deux jeux de clés ne sont pas interchangeables.
2. Peut-on placer une clé dans un frontend ou une mini-application ?
Non. Le code frontend est visible par les utilisateurs ; toute clé qui y figure doit être considérée comme compromise. La bonne pratique consiste à appeler votre propre backend, qui conserve la clé et relaie les appels au modèle.
3. Une même clé peut-elle servir à plusieurs projets ?
Techniquement oui, mais ce n'est pas recommandé. Une clé partagée ne permet pas de distinguer l'origine des appels, une fuite affecte toute l'activité et la facturation devient difficile à répartir. Séparez au minimum par service et par environnement.
4. Que faire en cas de fuite de clé ?
Révoquez ou supprimez immédiatement la clé dans la console, créez-en une nouvelle et mettez à jour la configuration côté serveur. Vérifiez en parallèle la facturation et les journaux d'appels pour détecter un usage anormal, et contactez le support de la plateforme si nécessaire.
5. Peut-on mélanger clé officielle et clé de passerelle ?
Non. Les systèmes d'authentification, les URL de base et les comptes de facturation diffèrent. Le symptôme le plus courant est une erreur 401, parfois une requête envoyée à la mauvaise adresse de service.
