Vercel AI Gateway : routage unifié des fournisseurs d'IA pour Next.js en 2026

Toute application d'IA sérieuse finit par se heurter au même casse-tête multi-fournisseurs. Vous commencez avec OpenAI, ajoutez Anthropic pour le contexte plus long de Claude, routez une partie du trafic vers Google pour Gemini Flash à bas prix, et glissez peut-être un peu de Mistral en repli open-weights. Soudain, votre .env contient six clés API, vos clients fournisseurs sont éparpillés dans les fichiers, et une seule panne d'OpenAI met tout le produit hors service.

Vercel AI Gateway réduit ce chaos à un seul point d'accès HTTP, une seule clé API et une seule relation de facturation. Vous continuez à coder avec Vercel AI SDK, mais chaque appel de modèle est désormais réparti, observable, cacheable et prêt à basculer par défaut.

Dans ce tutoriel vous construirez une application de chat de qualité production qui route intelligemment entre fournisseurs, bascule automatiquement quand l'un tombe en panne, met en cache les réponses coûteuses et suit la dépense en tokens par utilisateur — le tout sans changer le code applicatif au-delà d'un seul commutateur de configuration.

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Node.js 20 ou plus récent installé
• Un projet Next.js 15 (ou suivez l'étape de configuration ci-dessous)
• Un compte Vercel avec AI Gateway activé — inscription sur vercel.com
• Une familiarité de base avec React, TypeScript et Next.js App Router
• Un éditeur de code (VS Code recommandé)

Vous n'avez pas besoin de comptes séparés chez OpenAI, Anthropic ou Google pour suivre. Vercel AI Gateway fournit des crédits pour tester tous les fournisseurs supportés depuis un seul tableau de bord.

Ce que vous allez construire

Une application de chat multi-modèles qui :

1. Route via un seul point d'accès — chaque requête passe par la Gateway, jamais directement par un fournisseur
2. Bascule automatiquement quand un fournisseur renvoie des erreurs ou atteint la limite de débit
3. Met en cache les prompts identiques pour réduire la dépense en tokens sur les questions répétées
4. Suit l'usage par utilisateur via des en-têtes de métadonnées personnalisés
5. Compare les modèles en direct avec un panneau de réponses côte à côte pour le benchmarking

Pourquoi une Gateway bat les appels directs

Appeler directement les SDK des fournisseurs fonctionne bien dans un prototype. Cela tombe en panne dès que l'un de ces points compte :

• Fiabilité. Les pannes de fournisseurs arrivent tous les mois. Sans bascule, vos utilisateurs voient des erreurs au lieu de réponses.
• Visibilité des coûts. Chaque fournisseur a son tableau de bord, son calendrier de facturation et sa comptabilité de tokens. Réconcilier la dépense sur cinq fournisseurs est un cauchemar financier.
• Limites de débit. Le niveau 1 d'OpenAI vous plafonne à quelques milliers de requêtes par minute. Répartir la charge entre fournisseurs augmente votre plafond effectif.
• Changement de modèles. Essayer un nouveau modèle signifie chasser chaque appel openai.chat(). Avec une Gateway, vous changez une seule chaîne.
• Observabilité. Vous avez besoin de traces de requêtes, de taux d'erreur et de percentiles de latence par modèle. Le construire soi-même prend des semaines.

Une Gateway vous fournit tout cela en tant que service managé, facturé par passage de tokens plus une petite marge.

Étape 1 : configuration du projet

Créez un nouveau projet Next.js 15 avec TypeScript et Tailwind :

npx create-next-app@latest ai-gateway-demo \
  --typescript --tailwind --app --use-pnpm
 
cd ai-gateway-demo

Installez Vercel AI SDK v5 et le package fournisseur Gateway :

pnpm add ai @ai-sdk/gateway zod

Le package @ai-sdk/gateway expose une interface fournisseur unique qui sert de proxy vers tout modèle supporté par Vercel AI Gateway. Vous n'installez pas @ai-sdk/openai, @ai-sdk/anthropic ou aucun autre package spécifique à un fournisseur — c'est tout l'intérêt.

Étape 2 : configurer la Gateway

Dans votre projet Vercel, ouvrez l'onglet AI et cliquez sur Enable AI Gateway. Vercel provisionne automatiquement un point d'accès Gateway lié à votre projet et expose la clé API comme variable d'environnement AI_GATEWAY_API_KEY.

Si vous développez localement, liez le projet et téléchargez les variables d'environnement :

pnpm dlx vercel link
pnpm dlx vercel env pull .env.local

Votre .env.local devrait maintenant contenir :

AI_GATEWAY_API_KEY=vck_xxxxxxxxxxxxxxxxxxxx

Cette unique clé remplace toutes les clés de fournisseurs dont vous auriez normalement besoin.

Étape 3 : créer le client Gateway

Créez lib/ai.ts pour centraliser l'accès à la Gateway :

import { createGateway } from "@ai-sdk/gateway";
 
export const gateway = createGateway({
  apiKey: process.env.AI_GATEWAY_API_KEY!,
});
 
export const MODELS = {
  fast: "google/gemini-2.5-flash",
  smart: "anthropic/claude-sonnet-4.6",
  cheap: "openai/gpt-4o-mini",
  reasoning: "openai/o3-mini",
  openWeights: "mistral/mistral-large-latest",
} as const;
 
export type ModelKey = keyof typeof MODELS;

Chaque valeur dans MODELS est un identifiant de modèle pleinement qualifié que la Gateway reconnaît. Changer de fournisseur devient un changement d'une seule ligne n'importe où dans la base de code.

Étape 4 : construire une route de chat de base

Créez app/api/chat/route.ts :

import { streamText, convertToCoreMessages } from "ai";
import { gateway, MODELS, type ModelKey } from "@/lib/ai";
 
export const runtime = "edge";
export const maxDuration = 30;
 
export async function POST(req: Request) {
  const { messages, model = "smart" } = await req.json() as {
    messages: { role: string; content: string }[];
    model?: ModelKey;
  };
 
  const result = await streamText({
    model: gateway(MODELS[model]),
    messages: convertToCoreMessages(messages),
    system: "You are a concise, helpful assistant. Keep answers under 200 words unless asked for detail.",
  });
 
  return result.toDataStreamResponse();
}

Remarquez qu'il n'y a aucun code spécifique à un fournisseur. La Gateway résout anthropic/claude-sonnet-4.6 vers la bonne API en coulisses.

Étape 5 : construire l'interface de chat

Créez app/page.tsx avec une interface de chat minimale :

"use client";
 
import { useChat } from "ai/react";
import { useState } from "react";
 
const MODEL_OPTIONS = [
  { value: "fast", label: "Gemini 2.5 Flash (rapide, bon marché)" },
  { value: "smart", label: "Claude Sonnet 4.6 (meilleure qualité)" },
  { value: "cheap", label: "GPT-4o Mini (équilibré)" },
  { value: "reasoning", label: "OpenAI o3-mini (raisonnement)" },
  { value: "openWeights", label: "Mistral Large (poids ouverts)" },
];
 
export default function ChatPage() {
  const [model, setModel] = useState("smart");
  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
    api: "/api/chat",
    body: { model },
  });
 
  return (
    <main className="mx-auto max-w-2xl p-6">
      <h1 className="mb-4 text-2xl font-bold">Chat AI Gateway</h1>
 
      <select
        value={model}
        onChange={(e) => setModel(e.target.value)}
        className="mb-4 w-full rounded border p-2"
      >
        {MODEL_OPTIONS.map((opt) => (
          <option key={opt.value} value={opt.value}>{opt.label}</option>
        ))}
      </select>
 
      <div className="mb-4 space-y-3">
        {messages.map((m) => (
          <div key={m.id} className="rounded border p-3">
            <div className="text-xs text-gray-500">{m.role}</div>
            <div className="whitespace-pre-wrap">{m.content}</div>
          </div>
        ))}
      </div>
 
      <form onSubmit={handleSubmit} className="flex gap-2">
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="Demandez n'importe quoi..."
          className="flex-1 rounded border p-2"
          disabled={isLoading}
        />
        <button
          type="submit"
          disabled={isLoading || !input}
          className="rounded bg-black px-4 py-2 text-white disabled:opacity-50"
        >
          Envoyer
        </button>
      </form>
    </main>
  );
}

Lancez pnpm dev et vous devriez pouvoir discuter avec cinq modèles différents depuis la même interface, tous routés via la Gateway.

Étape 6 : ajouter la bascule automatique

Le trafic de production réel ne devrait jamais voir d'erreurs de fournisseurs. Configurez une chaîne de repli pour que si Claude est limité en débit, la requête soit retentée contre GPT-4o, et ainsi de suite.

Mettez à jour app/api/chat/route.ts :

import { streamText, convertToCoreMessages } from "ai";
import { gateway, MODELS, type ModelKey } from "@/lib/ai";
 
export const runtime = "edge";
 
const FALLBACK_CHAIN: ModelKey[] = ["smart", "cheap", "fast"];
 
async function streamWithFailover(
  messages: any[],
  preferred: ModelKey,
) {
  const chain = [preferred, ...FALLBACK_CHAIN.filter((m) => m !== preferred)];
 
  for (const key of chain) {
    try {
      return await streamText({
        model: gateway(MODELS[key]),
        messages,
        system: "You are a concise, helpful assistant.",
        experimental_telemetry: { isEnabled: true, functionId: `chat-${key}` },
      });
    } catch (err) {
      console.warn(`[gateway] ${key} failed, trying next provider`, err);
      if (key === chain[chain.length - 1]) throw err;
    }
  }
 
  throw new Error("All providers failed");
}
 
export async function POST(req: Request) {
  const { messages, model = "smart" } = await req.json();
  const result = await streamWithFailover(
    convertToCoreMessages(messages),
    model as ModelKey,
  );
  return result.toDataStreamResponse();
}

La Gateway prend également en charge des politiques de bascule côté serveur que vous pouvez configurer dans le tableau de bord, ce qui est préférable en production car la décision de routage a lieu avant que les tokens ne soient facturés.

Étape 7 : activer la mise en cache des réponses

Des prompts identiques arrivant dans une courte fenêtre ne devraient pas vous coûter des tokens deux fois. Vercel AI Gateway dispose d'une mise en cache sémantique intégrée — activez-la en ajoutant des en-têtes de cache :

const result = await streamText({
  model: gateway(MODELS[model], {
    headers: {
      "x-gateway-cache-ttl": "3600",
      "x-gateway-cache-mode": "semantic",
    },
  }),
  messages,
});

Trois modes sont disponibles :

• exact — ne correspond qu'aux prompts identiques au byte près
• semantic — correspond aux prompts similaires en sens (utilise des embeddings)
• disabled — contourne entièrement le cache

Pour un assistant de style FAQ, la mise en cache sémantique peut réduire la dépense en tokens de 40 à 70 pour cent car les utilisateurs ont tendance à poser la même question de nombreuses manières différentes.

Étape 8 : suivre l'usage par utilisateur

Pour les applications multi-tenants, vous voulez attribuer l'usage de tokens à des utilisateurs individuels. Passez un en-tête de métadonnées :

const result = await streamText({
  model: gateway(MODELS[model], {
    headers: {
      "x-gateway-user-id": userId,
      "x-gateway-tags": "tier:pro,feature:chat",
    },
  }),
  messages,
});

Le tableau de bord Gateway décompose alors la dépense par user-id et par toutes les étiquettes que vous fournissez. Vous pouvez aussi exporter ces données via l'API analytique pour facturer les clients en fonction de l'usage réel des modèles.

Étape 9 : ajouter un panneau de comparaison en direct

Une fonctionnalité phare du routage multi-fournisseurs est de permettre aux utilisateurs de voir le même prompt répondu par différents modèles côte à côte. Créez app/compare/page.tsx :

"use client";
 
import { useState } from "react";
 
const COMPARE_MODELS = ["smart", "fast", "reasoning"] as const;
 
export default function ComparePage() {
  const [prompt, setPrompt] = useState("");
  const [results, setResults] = useState<Record<string, string>>({});
  const [loading, setLoading] = useState(false);
 
  async function runComparison() {
    setLoading(true);
    setResults({});
 
    await Promise.all(
      COMPARE_MODELS.map(async (model) => {
        const res = await fetch("/api/chat", {
          method: "POST",
          body: JSON.stringify({
            messages: [{ role: "user", content: prompt }],
            model,
          }),
        });
        const text = await res.text();
        setResults((prev) => ({ ...prev, [model]: text }));
      }),
    );
 
    setLoading(false);
  }
 
  return (
    <main className="mx-auto max-w-5xl p-6">
      <h1 className="mb-4 text-2xl font-bold">Comparaison côte à côte des modèles</h1>
 
      <textarea
        value={prompt}
        onChange={(e) => setPrompt(e.target.value)}
        placeholder="Entrez un prompt pour le comparer entre modèles..."
        className="mb-4 h-32 w-full rounded border p-3"
      />
 
      <button
        onClick={runComparison}
        disabled={loading || !prompt}
        className="mb-6 rounded bg-black px-6 py-2 text-white disabled:opacity-50"
      >
        {loading ? "En cours..." : "Comparer les modèles"}
      </button>
 
      <div className="grid gap-4 md:grid-cols-3">
        {COMPARE_MODELS.map((model) => (
          <div key={model} className="rounded border p-4">
            <h3 className="mb-2 font-semibold">{model}</h3>
            <div className="whitespace-pre-wrap text-sm">
              {results[model] ?? (loading ? "Chargement..." : "")}
            </div>
          </div>
        ))}
      </div>
    </main>
  );
}

Ce schéma est inestimable pour l'ingénierie de prompts — vous pouvez voir instantanément comment Claude gère une demande nuancée par rapport à Gemini Flash ou o3-mini.

Étape 10 : configurer les limites de dépenses et les alertes

Ouvrez le tableau de bord AI Gateway dans Vercel et définissez :

1. Budget mensuel — la Gateway cesse de router les requêtes une fois le plafond atteint
2. Limites de débit par modèle — protection contre les boucles emballées ou les abus
3. Alertes — e-mail ou Slack lorsque vous franchissez 50, 75 ou 90 pour cent du budget

Ces garde-fous sont critiques pour toute fonctionnalité d'IA exposée au public. Sans eux, un seul utilisateur malveillant avec un script peut drainer des milliers de dollars de tokens en une nuit.

Tester votre implémentation

Vérifiez que chaque pièce fonctionne :

1. Routage de base — discutez avec chaque modèle et confirmez que vous obtenez une réponse
2. Bascule — définissez temporairement une mauvaise clé API pour un fournisseur dans le tableau de bord, envoyez une requête, et confirmez que le fournisseur suivant dans la chaîne la sert
3. Mise en cache — envoyez le même prompt deux fois et consultez le tableau de bord Gateway pour voir un appel facturé et un hit de cache
4. Suivi utilisateur — déclenchez des requêtes avec différents en-têtes x-gateway-user-id et confirmez que la ventilation par utilisateur apparaît
5. Comparaison — soumettez un prompt sur la page de comparaison et vérifiez que les trois modèles répondent

Dépannage

Erreurs d'authentification Confirmez que AI_GATEWAY_API_KEY est défini dans .env.local et que le projet est lié au projet Vercel où la Gateway est activée.

Modèle introuvable Vérifiez l'identifiant exact du modèle dans le tableau de bord Gateway. Les préfixes fournisseurs (anthropic/, openai/, google/) sont sensibles à la casse.

Le streaming se bloque en production Assurez-vous que votre route exporte runtime = "edge" ou définit maxDuration à au moins 30 secondes. Les timeouts serverless par défaut peuvent couper les générations longues.

Le cache ne fait jamais de hit Le cache sémantique a besoin de quelques requêtes pour réchauffer l'index d'embeddings. Lancez le même prompt trois ou quatre fois avant de juger le taux de hit.

Étapes suivantes

• Branchez la Gateway dans vos projets Vercel AI SDK existants — c'est un remplacement direct des imports fournisseurs directs
• Lisez la documentation Vercel AI Gateway pour des fonctionnalités avancées comme les règles de routage personnalisées
• Combinez avec Mem0 pour des assistants à état persistant multi-fournisseurs
• Ajoutez l'observabilité Langfuse au-dessus de la Gateway pour un traçage au niveau du prompt
• Associez avec la limitation de débit Arcjet pour protéger votre point d'accès Gateway contre les abus

Conclusion

Vercel AI Gateway transforme l'IA multi-fournisseurs d'un fardeau de maintenance en un changement de configuration d'une ligne. Vous obtenez fiabilité, observabilité, contrôle des coûts et liberté de changer de modèles sans réécrire de code. Pour toute application Next.js qui prend l'IA au sérieux en 2026, c'est le point de départ par défaut — il n'y a presque plus aucune raison d'appeler directement les SDK des fournisseurs.

Le schéma présenté ici passe à l'échelle d'un projet personnel à un système de production à plusieurs millions de requêtes. Commencez par la configuration de routage de base, ajoutez la bascule et la mise en cache à mesure que le trafic croît, et utilisez le tagging par utilisateur pour garder votre équipe finance satisfaite.