Une clé API Kimi est l'identifiant d'accès à la plateforme ouverte ; elle n'équivaut ni à un abonnement du site web ni à un solde de recharge. Beaucoup d'équipes bloquent lors de leur première intégration, non parce qu'elles ne savent pas utiliser le modèle, mais parce qu'elles se trompent de site, stockent mal la clé ou confondent un compte membre avec un compte API.

Cet article suit l'ordre réel des opérations : distinguer les systèmes de comptes, suivre le parcours d'inscription, de vérification et de création de clé, puis donner les méthodes de stockage, de rotation et de diagnostic des 401. Il compare enfin l'usage d'une clé officielle et d'une clé de passerelle. Modèles et prix sont ceux de la page Tarifs des modèles.

Remarque : Moonshot et Kimi sont des marques de leurs détenteurs respectifs ; cet article ne décrit que l'intégration technique. Les entrées de plateforme, les exigences de vérification et les règles de gestion des clés peuvent évoluer : la page actuelle de la console officielle fait foi.

1. Distinguer d'abord trois « comptes Kimi »

Type Entrée Usage Solde et clé
Abonnement web et application Kimi kimi.com Produit de conversation Indépendant de l'API
Plateforme Kimi (site chinois) platform.kimi.com Appels API en Chine Compte, solde et clé distincts
Plateforme Kimi (site international) platform.kimi.ai Appels API à l'étranger Totalement indépendant du site chinois

Les clés des sites chinois et international ne se mélangent pas. Utiliser une clé du site chinois sur l'adresse internationale, ou l'inverse, produit souvent un 401. Il existe une troisième voie : créer une clé sur ZSQH AI Gateway pour appeler plusieurs modèles, dont Kimi, avec une clé gérée par la passerelle et un solde logé dans le compte passerelle.

Déterminez d'abord quel site sert l'activité, puis inscrivez-vous. Ne cherchez pas une clé avec un compte membre tout en rechargeant la plateforme ouverte : ce sont deux produits différents.

2. Inscription et vérification d'identité

  1. Ouvrir platform.kimi.com et suivre les indications pour s'inscrire et se connecter.
  2. Ouvrir l'espace utilisateur et terminer la vérification personnelle ; pour un usage d'entreprise, la vérification d'entreprise.
  3. La vérification d'entreprise demande généralement la raison sociale, un compte bancaire au nom de l'entité et le code de crédit social unifié.
  4. La plateforme verse un montant aléatoire sur le compte d'entreprise ; après confirmation par la finance, saisissez ce montant : s'il correspond, la vérification passe.
  5. Recharger après la vérification. Un particulier peut recharger en ligne ; une entreprise peut aussi choisir le virement.
  6. Revenir à la console et vérifier l'état du compte, le solde et les modèles disponibles.

L'entité vérifiée ne peut passer que de personnel à entreprise ; le retour à un compte personnel n'est pas pris en charge. Réfléchissez donc au titulaire dès l'inscription. Facture, contrat et achat sont généralement liés à cette entité, et un changement ultérieur est pénible.

3. Étapes de création d'une clé API

  1. Après connexion, ouvrir https://platform.kimi.com/console/api-keys.
  2. Cliquer sur la création d'une clé API et la nommer selon « projet-environnement-usage », par exemple crm-prod-chat.
  3. Copier la clé générée. Si la page ne l'affiche qu'une fois, la déposer immédiatement dans un gestionnaire de secrets, pas dans une conversation.
  4. Envoyer une requête minimale en environnement de test pour vérifier clé, site et nom de modèle.
  5. Noter la date de création, le responsable, le projet associé et la date de rotation prévue.
  6. Utiliser des clés distinctes pour la production, les tests et le débogage personnel ; ne pas partager une clé entre plusieurs personnes.

Le périmètre de droits d'une clé et la possibilité de la ventiler par projet ou membre dépendent des options réellement proposées par la console. Ne présumez pas qu'un droit absent existe ; pour isoler, utilisez plusieurs comptes ou plusieurs clés avec des quotas applicatifs.

4. Rotation, révocation et réduction des droits

Traitez une clé comme un identifiant à durée de vie, pas comme un objet créé une fois pour toutes.

  • Rotation régulière : tous les 90 jours pour un projet courant ; plus court pour une activité critique.
  • Rotation immédiate en cas de mouvement de personnel : départ, mutation ou fin de mission externe, révoquer puis réémettre.
  • Révocation immédiate en cas de fuite : ne pas observer d'abord l'usage, désactiver puis enquêter.
  • Chevauchement : créer la nouvelle clé, déployer et valider, puis révoquer l'ancienne, pour éviter une coupure.
  • Moindre privilège : une clé pour un projet ou un environnement, afin de limiter l'impact.
  • Traçabilité : les journaux ne conservent que le préfixe et le nom de la clé, jamais la valeur complète.

La rotation n'est pas une formalité. Beaucoup d'incidents de « quota épuisé soudainement » viennent d'anciennes clés restées dans un script, un dépôt ou une conversation.

5. Stockage sécurisé : les variables d'environnement sont un minimum

La base consiste à ne pas écrire la clé dans le code. En local, utilisez un fichier .env ignoré par Git ; en production, utilisez le service de gestion de secrets de la plateforme ou l'injection de variables d'environnement.

# .env uniquement en local, jamais commité
MOONSHOT_API_KEY=votre_cle

# .gitignore doit au minimum contenir
.env
.env.*

Trois mesures supplémentaires :

  1. Aucune clé dans le front-end, le mobile ou une extension de navigateur ; tous les appels passent par le serveur.
  2. Filtrer l'en-tête Authorization dans les journaux, les rapports d'exception et l'APM, pour éviter une impression complète.
  3. Utiliser un gestionnaire de secrets dédié en CI/CD, sans affichage en clair dans les scripts de build.

Si plusieurs personnes partagent une machine de développement, les variables d'environnement ne suffisent pas à isoler. Une clé de développement par personne, avec un usage tracé par personne, permet de localiser un incident.

6. Ordre de diagnostic d'un 401

Un 401 ne signifie pas forcément une clé erronée. Suivez cet ordre ; quelques minutes suffisent généralement.

Symptôme Cause courante Traitement
invalid_authentication_error Format invalide, clé supprimée, copie incomplète Recréer et copier intégralement
incorrect_api_key_error Clé absente, en-tête mal orthographié Vérifier Authorization: Bearer
401 juste après un changement d'environnement Clés des sites chinois et international mélangées Aligner site et URL de base
403 permission_denied_error Liste blanche IP, interface non activée Vérifier droits de la console et sortie réseau
404 URL de base ou nom de modèle erroné Vérifier la liste des modèles et le chemin

Vérifiez point par point :

  1. À quel site appartient la clé, et l'URL de base correspond-elle.
  2. La clé contient-elle espaces, retours à la ligne ou guillemets.
  3. Les variables d'environnement sont-elles réellement chargées ? Affichez les premiers caractères pour vérifier.
  4. La clé a-t-elle été supprimée, désactivée ou renouvelée.
  5. L'en-tête est-il Authorization: Bearer <key>.
  6. Le chemin est-il /v1/chat/completions, sans /v1 en trop ou manquant.
  7. Réessayer avec une nouvelle clé pour distinguer un problème de clé d'un problème de configuration de passerelle.

7. Choisir entre clé officielle et clé de passerelle

Critère Connexion directe officielle ZSQH AI Gateway
Création Console de la plateforme Kimi Console de la passerelle
Système de comptes Site chinois ou international Compte passerelle
Règlement Recharge plateforme, facture selon règles officielles Recharge en yuans, facture selon règles de la passerelle
Périmètre Série Kimi Entrée unifiée multi-modèles
Usage Kimi uniquement, besoin des capacités officielles Changement de modèle, facture et clés unifiées

Pour Kimi uniquement, une équipe en Chine avec un accès officiel fluide, la connexion directe est la plus simple. Pour utiliser aussi DeepSeek, GLM et Claude, ou gérer plusieurs modèles avec une clé et une facture en yuans, la passerelle est plus adaptée. Les deux voies ne s'opposent pas : commencez par des tests via la passerelle, puis décidez du canal de production.

8. Checklist de déploiement en équipe

  • Définir l'entité d'usage de l'API et terminer la vérification correspondante.
  • Un site, un compte ; ne pas mélanger site chinois et site international.
  • Un projet, une clé ; un environnement, une clé.
  • La clé ne va que dans un gestionnaire de secrets, jamais dans un dépôt.
  • Fixer la périodicité de rotation et le responsable.
  • Activer l'alerte de solde pour éviter un refus d'appel ou un 429 dû à un impayé.
  • Distinguer 401, 403 et 429 dans la supervision, sans tout traiter comme une « clé invalide ».

Questions fréquentes

Que faire si la clé fuit ?

Révoquer ou supprimer immédiatement la clé dans la console, créer et déployer une nouvelle clé, puis vérifier l'usage et la facture. Ne changez pas seulement la chaîne dans le code : tant que l'ancienne clé n'est pas révoquée, elle reste utilisable.

Une clé peut-elle servir à plusieurs projets ?

Techniquement souvent oui, mais ce n'est pas recommandé. Le partage empêche d'attribuer usage, limitation et incident. Séparez les clés par projet, avec des quotas applicatifs, pour réduire le coût de diagnostic.

Une clé API Kimi expire-t-elle ?

L'existence d'une durée de validité dépend des règles actuelles de la console. Même si la plateforme n'impose pas d'expiration, une rotation proactive est recommandée, surtout après un mouvement de personnel ou pour une clé longtemps inutilisée.

Pourquoi encore un 401 après recharge ?

Vérifiez d'abord que la recharge et la clé appartiennent au même site et à la même entité. Testez ensuite avec une nouvelle clé pour exclure une ancienne clé supprimée, des variables non rafraîchies ou une valeur figée dans le code.

Peut-on mélanger clé officielle et clé de passerelle ?

Non. URL de base, système d'authentification et compte de solde diffèrent. Le mélange produit typiquement 401 ou 404 ; lors d'un changement, modifiez ensemble clé, URL de base et nom de modèle.

Pour aller plus loin

Créez d'abord une clé de test sur ZSQH AI Gateway, validez la chaîne avec une requête minimale, puis séparez les clés de production par projet. Modèles disponibles et mode de facturation sont ceux de la page Tarifs des modèles.

Lectures associées :