Tutoriel Cursor API : clé personnalisée, Base URL et modèles (2026)

Cursor est aujourd'hui l'un des éditeurs de code IA les plus utilisés. Il embarque ses propres quotas de modèles, mais accepte aussi une clé API et une Base URL personnalisées. Pour les équipes en Chine, utiliser sa propre passerelle présente trois avantages : un accès plus stable, une facturation unifiée et la possibilité de changer de modèle à tout moment.

Cet article explique la configuration de l'API personnalisée dans Cursor, les pièges courants, et comment choisir entre « abonnement » et « clé personnelle ».

Les versions de Cursor évoluent vite et les noms de menus peuvent changer. Cet article se réfère aux versions courantes d'octobre 2026 ; les Settings de votre version font foi.

1. Comprendre d'abord les deux modes d'utilisation de Cursor

1. Utiliser les quotas intégrés de Cursor

Prêt à l'emploi, facturé selon l'offre Cursor. Convient aux utilisateurs individuels qui ne veulent pas configurer et dont l'usage reste modéré.

2. Utiliser sa propre clé API

Renseignez dans Cursor la clé et la Base URL d'une interface tierce compatible OpenAI ; les coûts d'appel passent par votre propre compte API. Adapté lorsque :

l'accès officiel est instable depuis la Chine ;
l'équipe veut unifier facturation et quotas ;
vous devez imposer un modèle ou basculer entre plusieurs fournisseurs ;
vous voulez intégrer l'usage de Cursor à la gestion des coûts de l'entreprise.

À noter : même avec votre propre clé, certaines fonctions de Cursor peuvent exiger une offre valide. Les règles de la version et de l'offre Cursor actuelles font foi.

2. Préparer la clé API

Ouvrez ZSQH AI Gateway et connectez-vous.
Accédez à « Clés API », créez une clé nommée cursor-pc-travail.
Fixez un plafond de quota et une date d'expiration.
Copiez la clé et conservez-la dans un gestionnaire de mots de passe.
Rechargez le portefeuille et vérifiez le solde.

Base URL à utiliser :

https://ai.zhongshangqihang.com/v1

C'est l'adresse compatible OpenAI. La fonction d'API personnalisée de Cursor appelle généralement selon le protocole OpenAI : n'indiquez pas l'adresse racine Anthropic.

3. Configurer Cursor

Le chemin de menu varie légèrement selon les versions, généralement :

Cursor Settings → Models → OpenAI API Key

Étapes :

Ouvrez les paramètres Cursor (raccourci habituel : Cmd/Ctrl + ,).
Trouvez la zone Models ou OpenAI API Key.
Activez « Override OpenAI Base URL » ou l'interrupteur équivalent.
Renseignez la Base URL https://ai.zhongshangqihang.com/v1.
Renseignez la clé API sk-....
Ajoutez dans la liste des modèles les noms que vous voulez utiliser, par exemple gpt-5 ou claude-sonnet-4-5.
Enregistrez, puis créez une nouvelle conversation et testez avec le modèle personnalisé.

Si Cursor affiche « API Key invalid » :

vérifiez que la clé a été copiée en entier ;
vérifiez que la Base URL se termine par /v1 ;
vérifiez que le solde est suffisant ;
vérifiez que le nom du modèle est disponible pour le compte actuel.

4. Comment choisir le modèle

Les tâches courantes dans Cursor se répartissent en trois catégories :

Tâche	Modèle conseillé	Raison
Complétion quotidienne, petits bugs	Modèle léger/rapide	Faible latence, faible coût
Refactorisation multi-fichiers, agent complexe	Claude Sonnet / modèle GPT principal	Compréhension du code et appels d'outils plus stables
Raisonnement difficile, conception d'architecture	Opus / modèle haut de gamme	Capacité supérieure, coût plus élevé

Les noms de modèles doivent correspondre à la page Tarifs des modèles. La liste déroulante de Cursor peut n'afficher que les noms qu'il connaît ; si un modèle personnalisé n'apparaît pas, ajoutez-le manuellement ou choisissez un alias compatible.

5. Abonnement ou clé personnelle : lequel coûte moins

Il n'y a pas de réponse universelle : tout dépend du volume. Méthode d'estimation :

Comptez le nombre approximatif de requêtes par jour et la taille de contexte de chacune.
Consultez le prix et le quota de l'offre Cursor.
Estimez le coût en tokens du même volume avec la page de tarifs API.
Intégrez aussi la « stabilité, vitesse d'accès et gestion de la facturation ».

En pratique :

volume faible, un seul modèle : l'offre est souvent plus simple ;
volume élevé, changements fréquents de modèles, équipe nombreuse : clé personnelle + passerelle est généralement plus contrôlable ;
besoin d'un accès stable depuis la Chine : la valeur de la passerelle dépasse souvent l'écart de prix unitaire.

Les prix exacts sont ceux de la page Tarifs des modèles et de la page officielle des offres Cursor.

6. Problèmes courants et diagnostic

Symptôme	Cause possible	Traitement
401	Clé erronée, expirée, Base URL incorrecte	Recopier la clé ; confirmer `/v1`
404	Chemin dupliqué dans la Base URL	Ne renseigner que jusqu'à `/v1`, sans `/chat/completions`
Modèle indisponible	Nom incorrect ou non ouvert	Copier le nom depuis la page de tarifs
Timeout	Réseau ou proxy	Vérifier le réseau, alterner direct/proxy
Solde insuffisant	Pas de recharge ou quota épuisé	Recharger ; vérifier le quota de la clé
Réponse tronquée	Limite de contexte ou de sortie	Réduire le contexte ou augmenter la limite de sortie

7. Recommandations de sécurité

Créez une clé dédiée à Cursor, sans la partager avec les services en ligne.
Fixez un plafond de quota pour éviter que les requêtes d'arrière-plan de l'IDE ne consomment trop.
Ne conservez pas la clé durablement sur un ordinateur partagé.
Supprimez l'ancienne clé en cas de départ ou de changement de machine.
En équipe, utilisez une passerelle unifiée et une clé par membre pour faciliter l'audit.

8. Quelles équipes sont concernées

Prestataires et équipes externalisées : une clé par projet, coûts imputés par projet.
Startups : point d'entrée unifié, modèles interchangeables, pas de dépendance à un seul fournisseur.
R&D d'entreprise : gestion centralisée des membres, quotas, journaux et facturation.
Développeurs indépendants : accès plus stable depuis la Chine, paiement plus simple.

Pour aller plus loin

Commencez par vous inscrire sur ZSQH AI Gateway, créez une clé dédiée cursor et renseignez-la dans Cursor selon cet article. Une fois validé, ajustez le modèle principal à partir de la page Tarifs des modèles.