Cursor est un éditeur de code assisté par IA très répandu. Au-delà des modèles intégrés, il permet de renseigner sa propre clé API et une URL de base. Pour les équipes, connecter Cursor à une passerelle compatible OpenAI unifiée permet de fixer le chemin d'accès, de centraliser la facturation et de changer de modèle.

Cet article suit l'ordre des opérations réelles : préparation, configuration, vérification, limites et déploiement en équipe. Les noms de menus peuvent varier selon la version ; 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 ou Anysphere ; l'interface, les offres et les règles de facturation font foi sur les pages officielles de Cursor.

1. Distinguer deux « API Cursor »

La première est l'API ouverte par la plateforme Cursor elle-même, par exemple Cloud Agents et les interfaces d'administration ; la clé se crée dans le compte Cursor et sert à appeler les services Cursor. La seconde est l'apport de sa propre clé de fournisseur (BYOK) : on renseigne dans Cursor la clé d'un fournisseur de modèles pour que l'éditeur appelle les modèles avec votre compte. Cet article traite de la seconde.

Un prérequis est souvent négligé : les requêtes de modèles de Cursor sont relayées par les serveurs de Cursor, et non envoyées directement depuis votre machine. L'URL de base doit donc être accessible publiquement. Une passerelle joignable uniquement sur le réseau interne de l'entreprise provoquera généralement un timeout côté Cursor. ZSQH AI Gateway est un service public et n'est normalement pas concerné par cette limite.

2. Préparer la clé, l'URL de base et le nom du modèle

Préparez trois éléments : une clé API, une URL compatible et un ID de modèle exact.

  1. Ouvrez la page d'inscription de ZSQH AI Gateway, créez un compte et connectez-vous à la console.
  2. Allez dans « Clés API », créez une clé et nommez clairement son usage, par exemple cursor-portable-travail.
  3. Fixez un plafond de quota et une date d'expiration. Même pour un compte personnel, cela évite une consommation anormale.
  4. Copiez la clé et conservez-la dans un gestionnaire de mots de passe. La console ne l'affiche généralement en entier qu'une fois.
  5. Ouvrez Tarifs des modèles et notez l'ID du modèle à utiliser. Prix et modèles évoluent : référez-vous à l'affichage actuel de la page.

Les trois paramètres s'écrivent ainsi :

URL de base : https://ai.zhongshangqihang.com/v1
Clé API :     sk-... (créée dans la console, conservée uniquement dans le gestionnaire de mots de passe)
Modèle :      l'ID affiché actuellement sur la page « Tarifs des modèles »

L'URL de base utilise l'adresse compatible OpenAI et se termine par /v1. N'indiquez pas l'adresse racine d'Anthropic et n'ajoutez pas vous-même /chat/completions, sous peine de chemin dupliqué.

3. Renseigner la configuration dans Cursor

Le chemin habituel est Cursor Settings → Models → API Keys. Les options varient selon les versions, mais les étapes essentielles restent proches.

  1. Ouvrez Cursor Settings ; le raccourci est généralement Cmd/Ctrl + ,.
  2. Allez dans Models, puis dépliez la section API Keys.
  3. Activez OpenAI API Key, collez la clé créée et cliquez sur Save.
  4. Activez Override OpenAI Base URL et saisissez https://ai.zhongshangqihang.com/v1.
  5. Cliquez sur + Add Custom Model (parfois + Add model), saisissez l'ID de modèle de la page Tarifs et activez ce modèle.
  6. Dans le sélecteur de modèle de la conversation, choisissez ce modèle et envoyez une requête simple.

Si vous ne trouvez pas Override OpenAI Base URL, la version ou l'offre actuelle ne permet pas de diriger le trafic compatible OpenAI vers une adresse personnalisée. N'essayez pas en boucle : mettez à jour la version ou utilisez une installation proposant cette option.

Le nom du modèle est un identifiant de routage, pas une note. La casse, les traits d'union et le suffixe de version doivent correspondre à ceux de la passerelle. Une erreur se manifeste généralement par un modèle inexistant, une erreur 404 ou un rejet de requête.

4. Choisir les modèles

Cursor accepte plusieurs modèles personnalisés, mais le succès dépend de la disponibilité du modèle homonyme sur la passerelle et de la compatibilité du mode d'appel.

Cas d'usage Palier conseillé Saisie Points d'attention
Questions courantes, petites modifications Modèle léger et rapide Copier l'ID de la page Tarifs Faible latence, refactorisation complexe limitée
Modifications multi-fichiers, agents Modèle de code principal Copier l'ID de la page Tarifs Doit prendre en charge les appels d'outils
Conception d'architecture, diagnostic difficile Modèle haut de gamme Copier l'ID de la page Tarifs Coût plus élevé, à utiliser au besoin
Complétion Tab Modèle intégré de Cursor Ne passe pas par la clé personnalisée Le BYOK ne couvre pas la complétion

Le mode Agent peut dépendre de la Responses API ou des appels d'outils. Si la passerelle ne prend en charge que Chat Completions, certaines fonctions Agent échoueront. Dans ce cas, validez d'abord en conversation simple, puis déterminez s'il s'agit du modèle ou d'une incompatibilité de fonction.

Par ailleurs, Auto, Composer et la complétion Tab n'utilisent pas nécessairement votre clé. Selon la page d'aide de Cursor, la complétion Tab utilise toujours les modèles intégrés, et le mode Auto peut aussi être routé par Cursor. Considérez les modèles personnalisés comme un canal qui ne s'active qu'après une sélection explicite.

5. Vérifier que la configuration est active

Vérifier que Cursor répond ne suffit pas : la réponse peut venir du canal intégré. Procédez dans cet ordre.

  1. Créez une conversation vide pour éviter l'interférence de l'historique.
  2. Sélectionnez explicitement le modèle personnalisé dans le sélecteur, sans utiliser Auto.
  3. Envoyez une requête courte, par exemple demander l'explication d'un code de moins de dix lignes.
  4. Ouvrez l'usage ou les journaux de requêtes de la console de la passerelle et confirmez une entrée au même moment, avec le même modèle et la même clé.
  5. Notez le résultat. Si aucun journal n'apparaît, la requête n'a pas atteint la passerelle : revenez à l'URL de base et aux options.

Correspondance des erreurs courantes :

  • 401 ou 403 : clé erronée, désactivée ou quota épuisé.
  • 404 : chemin de l'URL de base incorrect ou nom de modèle inexistant.
  • 429 : limite de débit atteinte ou plafond de quota de la clé atteint.
  • Timeout : point de terminaison inaccessible ou problème de chemin réseau.
  • Seul l'Agent échoue : capacité d'interface incompatible, pas nécessairement un problème de clé.

6. Limites à connaître

  • Le BYOK couvre principalement les modèles de chat ; la complétion Tab reste sur les modèles intégrés de Cursor.
  • La prise en charge des clés OpenAI varie selon la version. La page d'aide de Cursor indique que la clé OpenAI personnelle ne couvre que les modèles de chat standard sans raisonnement ; les modèles de raisonnement et certaines nouvelles fonctions peuvent être indisponibles.
  • Les requêtes transitent par les serveurs de Cursor : le point de terminaison personnalisé doit être accessible publiquement.
  • Les requêtes avec clé personnelle ne bénéficient pas nécessairement de la politique de zéro rétention de Cursor ; le traitement des données dépend du fournisseur de modèles et de la passerelle. Les équipes ayant des exigences strictes de rétention doivent évaluer la situation au préalable.
  • Les offres Team et Enterprise peuvent continuer à facturer des frais de plateforme Cursor même avec une clé personnelle ; référez-vous à la page de facturation de Cursor.
  • Cursor évolue vite : noms de menus, modèles pris en charge et règles de facturation peuvent changer.

7. Déploiement en équipe

  • Commencez par un pilote restreint : trois à cinq développeurs, un modèle principal commun, pendant une semaine.
  • Enregistrez trois séries de données : taux de réussite des requêtes, latence moyenne, consommation quotidienne par personne.
  • Créez une clé distincte par personne sur la passerelle, avec des quotas individuels ; pas de clé partagée.
  • Tenez une table de correspondance des modèles : ce qui est saisi dans Cursor, ce que la passerelle fournit, et vers quoi basculer en cas d'échec.
  • Documentez la configuration en interne : URL de base, ID de modèles et traitement des erreurs courantes.
  • Après observation des coûts, décidez qui utilise une clé personnelle et qui reste sur le quota de l'offre. Les prix font foi sur la page Tarifs des modèles.
  • À chaque départ, changement de machine ou fin de projet, désactivez la clé correspondante le jour même.

8. Liste de sécurité

  • Une clé par usage, sans réutilisation entre appareils.
  • Fixer un plafond de quota et une date d'expiration.
  • Ne jamais écrire la clé dans le code, un fichier .env, une capture d'écran ou un ticket.
  • Ne pas conserver durablement la clé sur un ordinateur partagé.
  • Effectuer une rotation régulière ; en cas de doute sur une fuite, désactiver d'abord, puis enquêter.
  • Faire passer l'équipe par la passerelle et conserver les journaux de requêtes pour l'audit.
  • Pour les dépôts sensibles, vérifier d'abord si les données quittent la machine et vers quels services.

9. Questions fréquentes

Cursor prend-il en charge n'importe quelle interface compatible OpenAI ?

Pas nécessairement. L'utilisation dépend de la présence de Override OpenAI Base URL dans la version de Cursor, et de la compatibilité de l'interface avec le chemin et les paramètres réellement appelés. Validez d'abord en conversation simple, puis testez les fonctions Agent.

J'ai saisi ma clé, pourquoi Cursor demande-t-il encore un abonnement ?

Une clé personnelle ne débloque pas toutes les fonctions. Certaines fonctions de l'éditeur, la gestion d'équipe et les modèles intégrés restent soumis à l'offre ; référez-vous aux règles actuelles de Cursor.

Pourquoi la complétion Tab ne consomme-t-elle pas ma clé ?

Selon la page d'aide de Cursor, la complétion Tab utilise toujours les modèles intégrés de Cursor et ne passe pas par la clé personnelle. C'est un choix de conception du produit, pas une erreur de configuration.

Faut-il saisir l'adresse racine ou /v1 comme URL de base ?

Avec le protocole compatible OpenAI, saisissez l'adresse jusqu'à /v1. N'ajoutez pas /chat/completions, sous peine de chemin dupliqué et d'erreur 404.

Une équipe peut-elle partager une clé ?

Techniquement oui, mais ce n'est pas recommandé. Une clé partagée ne permet pas de distinguer la consommation par membre et complique l'investigation en cas de fuite. Une clé par personne, avec quotas et journaux, est plus sûre.

Étape suivante

Inscrivez-vous d'abord sur ZSQH AI Gateway, créez une clé dédiée à Cursor, puis renseignez l'URL de base et le modèle comme décrit ici. Une fois la conversation simple opérationnelle, ajustez le modèle principal et les quotas à partir de la page Tarifs des modèles.

À lire aussi :