Configurer une clé API dans Cursor : modèles, vérification et sécurité (2026)

Configurer un modèle personnalisé dans Cursor fait de la clé à la fois un laissez-passer et une frontière de coût et de sécurité. Une clé créée sans réflexion entraîne souvent une consommation anormale, des usages par membre impossibles à imputer, ou une ancienne clé encore active après un départ.

Cet article suit l'ordre « créer, associer, mapper, vérifier, renouveler, prévenir les fuites, gérer l'équipe » et fournit une liste applicable. Les noms d'interface évoluent selon les versions : référez-vous aux Cursor Settings de votre installation.

Remarque : Cursor est une marque d'Anysphere, Inc. Cet article est purement technique et n'implique aucune affiliation ni représentation avec Cursor/Anysphere ; les fonctionnalités et règles de facturation font foi sur les pages officielles de Cursor.

1. Identifier d'abord de quel type de clé il s'agit

L'expression « clé API Cursor » recouvre souvent trois choses :

Clé API de la plateforme Cursor : destinée aux Cloud Agents et interfaces d'administration de Cursor, créée dans le compte Cursor.
Clé d'un fournisseur de modèles : émise par OpenAI, Anthropic, Google, Azure, AWS Bedrock, etc., saisie dans la zone API Keys de Cursor.
Clé de passerelle : émise par un service compatible comme ZSQH AI Gateway, généralement préfixée sk-, appelant plusieurs modèles via le protocole compatible OpenAI.

Cet article traite de la troisième dans Cursor. Elle ne sert pas à se connecter à Cursor et ne permet pas d'appeler les interfaces de la plateforme Cursor. Une clé de passerelle se saisit dans OpenAI API Key avec une URL de base personnalisée ; la placer dans un champ dédié Anthropic ou Google ne fonctionne généralement pas.

2. Créer une clé : définir les limites avant de copier

Avant de créer une clé, répondez à trois questions : pour qui, pour quel projet, et quel plafond de consommation. Une fois ces réponses posées, la gestion ultérieure sera bien plus simple.

Ouvrez la page d'inscription de ZSQH AI Gateway et connectez-vous à la console.
Allez dans « Clés API » et créez une clé.
Donnez un nom incluant l'utilisateur et l'appareil, par exemple cursor-zhang-macbook, pas seulement test.
Fixez un plafond de quota et une date d'expiration ; si la console gère le périmètre de modèles, limitez les modèles disponibles par projet.
Rechargez et vérifiez le solde, pour éviter de découvrir après configuration que l'appel est impossible.
Copiez la clé dans un gestionnaire de mots de passe, sans l'envoyer d'abord dans un outil de chat ou un ticket.

Dans le gestionnaire, consignez au format suivant pour faciliter rotation et passation :

Usage : cursor-ordinateur-travail
URL de base : https://ai.zhongshangqihang.com/v1
Clé : sk-... (uniquement dans le gestionnaire de mots de passe)
Modèle : ID affiché actuellement sur la page « Tarifs des modèles »

La clé n'est généralement affichée en entier qu'une fois. Si vous la perdez, créez-en une nouvelle et supprimez l'ancienne, sans tenter de la retrouver. Modèles et prix évoluent : référez-vous à la page Tarifs des modèles.

3. Associer la clé dans Cursor

Le chemin courant est Cursor Settings → Models → API Keys. Prêtez attention à l'état d'enregistrement à chaque étape.

Ouvrez Cursor Settings, généralement avec Cmd/Ctrl + ,.
Allez dans Models, puis développez API Keys.
Ouvrez OpenAI API Key, collez la clé et cliquez sur Save.
Ouvrez Override OpenAI Base URL et saisissez https://ai.zhongshangqihang.com/v1.
Cliquez sur + Add Custom Model (parfois + Add model), saisissez l'ID exact du modèle et activez-le.
Sélectionnez ce modèle dans la conversation et envoyez une requête courte.

Trois erreurs fréquentes :

L'URL de base est l'adresse web https://ai.zhongshangqihang.com, sans /v1.
L'URL de base va jusqu'à /chat/completions, ce qui duplique le chemin et renvoie 404.
La clé de passerelle est saisie dans le champ Azure OpenAI ou Bedrock. Ces champs correspondent à l'authentification propre à ces clouds et ne conviennent pas à une passerelle compatible ordinaire.

Si votre version n'a pas d'Override OpenAI Base URL, elle ne prend pas en charge les adresses compatibles personnalisées. Ne contournez pas par un autre champ : mettez à jour ou utilisez une version proposant cette option.

4. Mapping des modèles : transformer un « nom » en table maintenable

Le nom du modèle n'est pas un libellé d'affichage mais un identifiant de routage. L'équipe gagne à tenir une table de correspondance avec au minimum : usage, ID saisi dans Cursor, modèle correspondant côté passerelle, limites de capacité et date de retrait.

Usage	Saisie dans Cursor	Référence côté passerelle	Point de vérification
Questions quotidiennes	ID de modèle léger	Modèle homonyme de la page tarifs	Nom strictement identique
Modèle principal de code	ID du modèle principal	Modèle homonyme de la page tarifs	Support des appels d'outils
Tâches à contexte long	Version à contexte long	Modèle homonyme de la page tarifs	Limite de contexte
Secours en cas de panne	ID du modèle de secours	Modèle homonyme de la page tarifs	Bascule manuelle possible

N'utilisez pas un nom d'affichage à la place de l'ID et ne devinez pas le suffixe de version. Une erreur se manifeste souvent par « modèle inexistant », un 404 ou un rejet de requête. Quand la passerelle change de modèle, mettez à jour Cursor et la documentation interne.

5. Vérifier : configuration, requête, facturation

Ne vous contentez pas de vérifier « s'il y a une réponse » : elle peut venir du canal intégré. Trois niveaux sont plus fiables.

Configuration : la clé est enregistrée, l'URL de base se termine par /v1, le modèle personnalisé est activé.
Requête : ouvrez une conversation vide, sélectionnez explicitement le modèle personnalisé et envoyez une requête courte.
Facturation : ouvrez l'usage ou les logs de requêtes de la console et confirmez une entrée à l'heure, au modèle et à la clé correspondants. Sans entrée, la requête n'a pas atteint la passerelle.

Correspondance des erreurs courantes :

401 ou 403 : clé erronée, désactivée ou quota épuisé.
404 : chemin d'URL de base incorrect ou nom de modèle inexistant.
429 : limitation déclenchée ou plafond de quota atteint.
Timeout : point de terminaison inaccessible ou chemin réseau défaillant.
Conversation normale mais Agent en échec : capacité d'interface incompatible, pas nécessairement la clé.

Pendant le test, créez une clé à faible quota dédiée, puis passez à la clé de production après validation, pour éviter de coller la clé définitive dans plusieurs fenêtres.

6. Rotation, révocation et gestion d'incident

Renouvelez la clé à période fixe, par exemple tous les 90 jours, ou immédiatement après un changement de membre ou d'appareil. Une rotation n'est pas une suppression-recréation : on met d'abord en parallèle, puis on bascule.

Créez une nouvelle clé aux mêmes droits, avec un suffixe de date dans le nom.
Remplacez la clé dans Cursor et enregistrez.
Envoyez une requête de test et vérifiez que les logs de la passerelle mentionnent la nouvelle clé.
Observez un temps le taux d'erreur et l'usage pour repérer d'éventuels clients oubliés.
Désactivez l'ancienne clé, puis supprimez-la après un délai.

En cas de fuite suspectée, inversez l'ordre : désactivez ou supprimez d'abord la clé, puis examinez l'usage anormal, la source et la période, prévenez l'équipe, vérifiez dépôts et logs, et renouvelez si besoin les autres identifiants concernés. Lors d'un départ ou d'un changement de machine, désactivez la clé le jour même, sans attendre le prochain audit.

7. Prévenir les fuites : par où une clé peut sortir

Code et fichiers de configuration : .env, configuration de conteneur, notebooks peuvent être commités. Utilisez un gestionnaire de secrets et scannez avant commit.
Captures et enregistrements d'écran : la page de réglages affiche la clé en entier. Masquez avant capture et n'ouvrez pas le champ pendant une démo.
Chats et tickets : n'envoyez pas la clé complète à un collègue ou au support. Pour identifier, donnez le nom ou les quatre derniers caractères.
Synchronisation des réglages IDE et extensions : vérifiez la portée de synchronisation et les permissions des extensions ; les appareils d'entreprise devraient avoir une liste blanche d'extensions.
Ordinateur partagé : utilisez un compte système distinct, ne cochez pas la conservation longue, déconnectez-vous après usage.
Logs et rapports d'erreur : les logs de débogage peuvent contenir des en-têtes. Supprimez les informations d'authentification avant envoi.
Chemin de transmission : selon la page d'aide de Cursor, la clé est envoyée chiffrée aux serveurs de Cursor avec la requête et n'y est pas conservée ; mais l'apport de clé ne bénéficie pas forcément d'une politique de rétention nulle. Utilisez une clé dédiée à quota limité.

8. Politique d'équipe : rendre les clés gérables

Une clé par personne ; les services partagés ont leur propre clé, sans mélange avec les clés individuelles.
Fixez des plafonds, des dates d'expiration et une liste blanche de modèles uniformes.
Passez autant que possible par une passerelle unifiée pour conserver les logs de membres, modèles et usage.
Contrôlez chaque mois : clés inutilisées depuis longtemps, clés au-dessus du quota, hausse anormale des échecs d'authentification.
Définissez la classification des données : les dépôts sensibles n'utilisent que des modèles et canaux déjà évalués.
Intégrez création, passation et désactivation des clés aux listes d'arrivée et de départ.
En offre équipe, même avec l'apport de clé, des frais de plateforme peuvent s'appliquer : le calcul de coût dépend de la page de facturation Cursor et de la page Tarifs des modèles.

9. Liste de dépannage

La clé collée contient un espace ou un saut de ligne : supprimez et recopiez entièrement.
L'URL de base contient /chat/completions en trop : ne gardez que /v1.
Le nom du modèle omet le suffixe de version : copiez-le tel quel depuis la page tarifs.
Le quota de la clé est épuisé : vérifiez solde et quota dans la console, ajustez le plafond si nécessaire.
Limite d'offre : vérifiez si l'offre Cursor actuelle autorise l'apport de clé et les fonctions associées.
Point de terminaison inaccessible : vérifiez que l'URL de base est publique et testez hors navigateur avec une requête simple.
Agent en échec mais conversation normale : suspectez d'abord une incompatibilité de capacités, pas une clé invalide.
La complétion Tab n'utilise pas la clé : selon la documentation Cursor, elle s'appuie sur les modèles intégrés ; c'est le comportement attendu.

10. Questions fréquentes

Quelle différence entre une clé API Cursor et une clé API de modèle ?

La première désigne généralement une clé émise par la plateforme Cursor pour ses propres interfaces ; la seconde est émise par un fournisseur de modèles ou une passerelle pour appeler des modèles. Cet article configure la seconde ; les deux ne sont pas interchangeables.

Peut-on limiter une clé à un seul modèle ?

Cela dépend de la console de la passerelle et de ses réglages de périmètre ou de permissions. Sinon, utilisez au minimum une clé dédiée avec plafond de quota pour limiter l'impact, et vérifiez le modèle réellement appelé dans les logs.

La rotation d'une clé interrompt-elle les conversations en cours ?

Les requêtes déjà parties peuvent ne pas être affectées, mais les suivantes utiliseront la nouvelle clé. Basculez aux heures creuses, envoyez immédiatement une requête de test, puis désactivez l'ancienne clé.

Que faire en premier après une fuite de clé ?

Désactivez ou supprimez la clé, puis recherchez l'usage anormal et l'origine des appels. Ne perdez pas de temps à confirmer le chemin de fuite : limitez d'abord la perte. Vérifiez ensuite dépôts, logs et historiques de chat, et renouvelez les autres identifiants si nécessaire.

Le quota gratuit suffit-il pour tester ?

Cela dépend des activités en cours dans la console et de la page Tarifs des modèles. Pour tester, utilisez une clé à faible quota et vérifiez seulement la connectivité et le nom du modèle, sans solliciter le trafic de production.

En résumé

La configuration de la clé dans Cursor n'est pas complexe ; la difficulté est la gestion dans la durée : nom traçable, quota plafonné, modèles mappés, fuite contenue. Inscrivez-vous d'abord sur ZSQH AI Gateway, créez une clé dédiée à Cursor, puis resserrez progressivement les permissions selon la politique d'équipe.