Vercel AI Gateway : un budget pour chaque utilisateur

Un agent de code qui s’emballe ne doit plus partager le même coupe-circuit financier que votre application en production. Le 31 août 2026, Vercel AI Gateway a ajouté des budgets par utilisateur : les dépenses des clés API attribuées à un membre peuvent désormais être stoppées sans interrompre une clé de production attribuée à l’équipe, à condition que cette clé et l’équipe disposent encore d’un budget. Ce nouveau contrôle change la façon dont une équipe maîtrise sa facture, pas le prix des modèles.

Vercel AI Gateway : le principe en une phrase

Attribuez un budget individuel aux clés des agents utilisés par une personne, et laissez les clés de production partagées sous la responsabilité de l’équipe.

Tout tient dans ce mécanisme. Le budget d’un utilisateur cumule les dépenses de toutes les clés API AI Gateway attribuées au même membre. Une fois ce budget épuisé, les nouvelles requêtes effectuées avec ces clés renvoient un code HTTP 402, tandis que le trafic hors du budget de cet utilisateur peut continuer.

Avant cette nouveauté, Vercel permettait déjà de plafonner les dépenses d’une équipe, d’un projet ou d’une clé API. Le périmètre utilisateur vient compléter ces contrôles pour répondre à un autre besoin : un développeur peut employer plusieurs clés dans Codex, Claude Code, Cursor ou une autre charge de travail non supervisée, tandis que la direction financière souhaite fixer un seul plafond pour l’ensemble de ses dépenses sur la gateway.

Quelles dépenses sont réellement imputées à un utilisateur ?

Le réglage essentiel est l’attribution des dépenses : il s’agit simplement de l’étiquette de propriété que Vercel associe à une clé API pour comptabiliser son budget.

Les nouvelles clés sont attribuées par défaut à l’utilisateur (User). Par souci de rétrocompatibilité, les anciennes clés sans attribution restent rattachées à l’équipe (Team). Une clé créée via l’API sans metadata.spendAttribution est elle aussi comptabilisée au niveau de l’équipe.

Il en résulte quatre parcours de requête distincts :

La dépense n’est pas répartie entre ces budgets : elle alimente simultanément tous les compteurs concernés. Une requête envoyée avec une clé attribuée à un membre doit respecter le budget de la clé, celui de l’utilisateur et celui de l’équipe. Dès que l’un des trois est épuisé, la requête est bloquée.

C’est pourquoi le trafic de production partagé exige une configuration explicite. Si un développeur crée une nouvelle clé pour une application destinée aux clients, cette clé lui est attribuée par défaut. Son budget personnel peut alors arrêter l’application. Sur la page des clés API d’AI Gateway, modifiez son réglage Spend attribution et choisissez Team : seuls les budgets de la clé et de l’équipe s’appliqueront.

Le calcul économique n’est plus le même

Les plafonds individuels transforment un risque mutualisé en enveloppes que l’on peut attribuer avant l’arrivée de la facture.

Prenons un exemple donné à titre d’illustration, et non un tarif Vercel. Supposons qu’une équipe de 8 personnes dispose d’un budget mensuel de $1,000. Sept membres reçoivent le budget par défaut de $50 par mois. Un responsable obtient un budget personnalisé de $150, car son rôle nécessite davantage de tâches confiées aux agents.

L’enveloppe dédiée aux clés personnelles est donc la suivante :

7 × $50 + 1 × $150 = $500 per month

Ces $500 ne s’ajoutent pas au budget de l’équipe : ils sont inclus dans celui-ci. Si les clés attribuées aux membres consomment d’abord la totalité de ces $500, ces $500 sont également déduits du plafond d’équipe de $1,000. Dans ce scénario simplifié, il reste alors $500 avant d’atteindre la limite de l’équipe pour le trafic de production attribué à Team.

Rien n’est toutefois réservé. La production peut dépenser en premier, et chaque requête doit toujours disposer d’une marge suffisante sous le plafond de l’équipe. L’amélioration est plus ciblée : aucun membre ne peut dépasser son enveloppe avec ses clés attribuées avant de priver tous les autres d’accès.

Cette approche diffère du contrôle natif d’OpenAI, où un agent doit disposer de son propre projet pour bénéficier d’un plafond de projet réellement appliqué. Notre guide des plafonds de dépenses de l’API OpenAI détaille ce modèle d’isolation. Chez Vercel, le périmètre utilisateur peut englober plusieurs clés attribuées à un même membre, sans créer un projet par personne.

Cette fonctionnalité ne réduit pas le prix des tokens. AI Gateway continue de facturer les tarifs catalogue des fournisseurs, sans majoration sur les tokens ni frais de plateforme. Le bénéfice réside dans la limitation des pertes et dans une responsabilité plus lisible, pas dans une inférence moins chère.

Quatre équipes dont le workflow change vraiment

Une équipe produit qui utilise plusieurs agents de code

Définissez un budget utilisateur par défaut pour l’équipe, puis accordez un montant personnalisé aux personnes qui consomment davantage. Un développeur peut faire tourner différents agents avec des clés distinctes : toutes ces clés restent regroupées sous un seul plafond personnel.

Le gain est concret pour les boucles lancées pendant la nuit. Si un agent réessaie sans fin une tâche en échec, les requêtes de ce développeur s’arrêtent sans couper automatiquement un service de production attribué à l’équipe.

Une agence qui protège sa marge client

Attribuez à chaque opérateur une clé personnelle et une enveloppe par défaut. Ajoutez un budget personnalisé pour la personne chargée d’une migration gourmande en modèles ou d’un sprint client de courte durée.

Vous obtenez ainsi une exception nominative. Il devient possible d’autoriser davantage de dépenses pour une personne sans relever l’enveloppe de tous ses collègues ni faire du budget global de l’agence l’unique coupe-circuit.

Une équipe plateforme qui sépare les personnes de la production

Passez en revue toutes les clés AI Gateway et attribuez les services partagés à Team. Conservez l’attribution aux créateurs pour les clés personnelles utilisées par les agents de code.

Le résultat est une véritable isolation des pannes. L’épuisement du budget d’une personne bloque le trafic de ses agents, tandis qu’une charge destinée aux clients continue de fonctionner jusqu’à épuisement de son propre budget de clé ou du budget de l’équipe.

Une équipe finance ou opérations responsable de la politique

Un Owner peut accorder l’autorisation AI Gateway Budget Manager sans céder l’intégralité du rôle Owner. Cette personne peut gérer les budgets utilisateurs, les valeurs par défaut et l’attribution des clés. De leur côté, tous les rôles de l’équipe à l’exception de Contributor peuvent consulter les pages budgétaires.

La politique a ainsi un véritable responsable opérationnel. La finance définit l’enveloppe, l’ingénierie peut la consulter et une modification budgétaire n’a plus à attendre l’unique personne propriétaire de toute l’équipe Vercel.

Configurer les budgets sans rattacher la production à une personne

Les budgets utilisateurs nécessitent la version 59.6.2 ou ultérieure de la CLI Vercel. Les commandes ci-dessous ont été vérifiées avec la version 59.6.2 lors de ce test.

1. 1

   Mettre à niveau la CLI et vérifier sa version

   Lancez la commande de mise à niveau indiquée dans la documentation, puis vérifiez que la version installée est au moins la 59.6.2.

   vercel upgrade
   vercel --version

2. 2

   Définir l’enveloppe par défaut

   Dans cet exemple, chaque membre sans budget utilisateur personnalisé reçoit sa propre enveloppe mensuelle de $50. Il ne s’agit pas de $50 partagés par tout le groupe.

   vercel ai-gateway budgets defaults set user --limit 50 --refresh-period monthly

3. 3

   Attribuer un plafond personnalisé au membre le plus actif

   Le budget personnalisé remplace la valeur par défaut pour cette personne. Vercel accepte une adresse e-mail, un nom d’utilisateur ou un identifiant utilisateur.

   vercel ai-gateway budgets set user lead@example.com --limit 150 --refresh-period monthly
   vercel ai-gateway budgets list

4. 4

   Rattacher les clés partagées à l’équipe

   Ouvrez AI Gateway, accédez à API Keys, modifiez chaque clé utilisée par une charge partagée ou destinée aux clients, puis réglez Spend attribution sur Team. Les nouvelles clés étant attribuées par défaut à User, intégrez cette vérification à la création de chaque clé de production.

5. 5

   Ajouter des alertes là où une personne doit intervenir

   Les budgets personnalisés peuvent envoyer un e-mail à 50%, 75% et 100% du plafond. Les alertes sont désactivées par défaut, et un budget par défaut n’envoie aucune alerte. Créez donc un budget personnalisé lorsqu’une personne identifiée doit recevoir des avertissements avant le blocage.

Les budgets mensuels sont réinitialisés le premier jour du mois à minuit UTC. Les budgets quotidiens le sont à minuit UTC, les budgets hebdomadaires le lundi à minuit UTC, tandis que none crée un plafond cumulatif qui ne se réinitialise jamais.

Tester le blocage et la reprise en staging

Aucun budget d’une équipe Vercel active n’a été modifié pour cet article, car le test ne disposait pas d’une équipe ni d’une clé jetables. C’est donc à vous d’effectuer la vérification en staging. Le comportement du code 402 et les délais de propagation ci-dessous correspondent au fonctionnement documenté par Vercel, et non à un benchmark réalisé ici sur un compte.

Utilisez un membre exclusivement réservé au staging ainsi qu’une clé attribuée à ce membre. N’effectuez pas ce test avec une clé de production.

1. 1

   Commencer avec une dépense visible

   Exécutez vercel ai-gateway budgets list pour vérifier les dépenses du membre de staging sur la période en cours. Si elles dépassent déjà le minimum documenté de $1, vous pouvez tester le franchissement du plafond sans générer un dollar supplémentaire de trafic.

2. 2

   Abaisser le plafond de l’utilisateur de staging

   La modification d’un budget conserve les dépenses déjà accumulées pendant la période en cours. Fixez le plafond de l’utilisateur de staging à $1, puis laissez le changement se propager.

   vercel ai-gateway budgets set user staging@example.com --limit 1 --refresh-period monthly

3. 3

   Envoyer une requête avec la clé de ce membre

   Exportez la clé de staging attribuée au membre dans AI_GATEWAY_API_KEY, puis reprenez le format de requête HTTP brute documenté par Vercel.

   curl https://ai-gateway.vercel.sh/v1/chat/completions \
     -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "openai/gpt-5.6-sol",
       "messages": [
         {
           "role": "user",
           "content": "Invent a new holiday and describe its traditions."
         }
       ]
     }'

   Une fois le budget utilisateur actif et épuisé, la requête doit renvoyer un code HTTP 402 avec le type d’erreur quota_for_entity_exceeded. Si le code 402 s’accompagne d’un autre type, le problème peut venir du solde de crédits de l’équipe plutôt que d’un budget.

4. 4

   Relever le plafond et relancer la requête

   Relevez le plafond personnalisé au-dessus du montant affiché par budgets list. La commande documentée ci-dessous utilise $100.

   vercel ai-gateway budgets set user staging@example.com --limit 100 --refresh-period monthly

   Les modifications budgétaires se propagent généralement en quelques dizaines de secondes, mais ce délai peut atteindre environ cinq minutes pour une clé active. Patientez, puis envoyez de nouveau la même requête. Elle devrait aboutir, sauf si un autre budget applicable — celui de la clé ou celui de l’équipe — est épuisé.

5. 5

   Rétablir la politique prévue

   Réappliquez au membre de staging le plafond personnalisé prévu. Supprimer le budget personnalisé ne permet pas toujours de débloquer la situation : lorsqu’un budget par défaut existe, l’utilisateur bascule sur celui-ci. Si ce dernier est déjà épuisé, le trafic reste bloqué.

Les deux limites à ne pas oublier

Premièrement, les dépenses BYOK échappent à tous les budgets AI Gateway. Lorsque la gateway utilise vos propres identifiants fournisseur, ces dépenses sont comptabilisées séparément et aucun plafond utilisateur ne peut les contenir. Une requête BYOK en échec peut aussi se rabattre sur les identifiants système de Vercel et débiter le solde de crédits AI Gateway de l’équipe.

Deuxièmement, les propres pages de Vercel se contredisent actuellement au sujet des app tokens. L’annonce du 31 août indique que les plafonds utilisateurs couvrent les clés API attribuées ainsi que les app tokens. La documentation actuelle sur les budgets affirme au contraire que les app tokens ne sont attribués à aucun membre et ne sont jamais pris en compte dans un budget utilisateur.

La mesure à prendre lundi

Agissez cette semaine si plusieurs membres utilisent des agents de code ou d’autres charges non supervisées avec leurs propres clés AI Gateway. Vous pouvez attendre si tout votre trafic passe uniquement par des tokens OIDC de projet ou par des identifiants fournisseur BYOK, car les budgets utilisateurs ne contrôlent pas ces parcours. Pour un indépendant disposant d’une seule clé et d’un seul budget d’équipe, l’impact reste limité.

Lundi, classez chaque clé de la gateway dans l’une de ces deux catégories : PERSONNE ou PARTAGÉE. Commencez par attribuer les clés de production partagées à Team. Définissez ensuite un budget utilisateur mensuel par défaut, puis ajoutez uniquement les exceptions personnalisées que l’entreprise peut justifier. Enfin, exécutez en staging le test du code 402 de bout en bout : blocage, relèvement du plafond et reprise. La configuration n’est prête que lorsque la production reste hors du budget d’une personne et que l’opérateur sait identifier le plafond à l’origine d’un blocage.

Pour recevoir d’autres conseils pratiques sur le contrôle des coûts de l’IA et les workflows de production, inscrivez-vous à la newsletter.