Trocando de provider de imagem no Next.js com o AI Gateway da Vercel

Montei um app Next.js↳Next.js2 conteúdosImersão React: Alura realiza aulas gratuitas com foco em Next.JSGestão Dev & TI · jan 2021Criando sua primeira aplicação com RemixDev (Back & Front) · set 2024Ver tudo em Dev (Back & Front) → com App Router para trocar de modelo pelo AI↳Inteligência artificial440 conteúdosUX e IA: Transformando Experiências Digitais com Inteligência ArtificialProduto & UX · jan 2025MCP: O que é e por que você vai ouvir falar disso em breve?AI · jul 2025IA generativa e a urgência de reconstruir nossa relação com a verdadeAI · jun 2025Ver tudo em AI → Gateway mudando uma linha, e onde a doc oficial ainda deixa buracos.

O que me atraiu no AI Gateway da Vercel foi a promessa de "uma chave, centenas de modelos": um endpoint único, com fallback automático entre providers e, segundo a doc oficial, sem markup sobre tokens (inclusive no modo Bring Your Own Key). Resolvi testar isso na prática num app Next.js, isolando o nome do modelo pra conseguir trocar de provider mudando o mínimo de código.

Nota da redação: o título deste tutorial menciona troca de provider de imagem, mas o código demonstrado e testado cobre apenas geração de texto (generateText), que é o que a documentação oficial do AI Gateway apresenta com exemplos verificáveis. A parte de geração de imagem não foi implementada nem executada aqui: a doc consultada não expõe endpoint nem nome de modelo de imagem, e por isso o autor optou por não simular um código funcional que poderia não existir. Trate a seção sobre imagem como orientação conceitual, não como algo pronto para produção sem validação prévia no seu catálogo.

Nota honesta e importante: a doc do AI Gateway que usei traz exemplo de código só para chat/texto com generateText (a famosa pergunta sobre a capital da França). Embeddings aparecem apenas como recurso listado, sem exemplo. E não há, na página principal do Gateway, exemplo de geração de imagem nem um endpoint de imagem exposto ali. Por isso este tutorial foca no que é verificável hoje (texto via AI SDK) e trata a parte de imagem com honestidade: mostro o caminho, mas deixo claro o que você precisa confirmar no seu catálogo antes de subir.

Setup do projeto

Comecei com um App Router limpo. Uso as flags explícitas pra evitar os prompts interativos que o CLI atual dispara (turbopack, eslint, tailwind, src dir, import alias):

npx create-next-app@latest gateway-ai --ts --app --eslint --no-tailwind --no-src-dir --import-alias "@/*" --yes
cd gateway-ai
npm i ai

O pacote ai é o AI SDK da Vercel, e a doc do Gateway confirma que ele funciona com AI SDK v5 e v6. É o que vou usar de fato no Route Handler, então nada de instalação órfã.

A autenticação do Gateway é por token. Criei .env.local:

AI_GATEWAY_API_KEY=seu_token_aqui

Primeiro tropeço: deixei o token num Client Component achando que ia "testar rápido". Nunca faça isso: a chave vaza pro bundle enviado ao navegador. Qualquer chamada que use a chave tem que rodar no servidor (Route Handler ou Server Action). O AI SDK lê AI_GATEWAY_API_KEY do ambiente automaticamente, então basta a variável existir no servidor.

Route Handler no servidor

Criei app/api/gen/route.ts. A ideia central é isolar o nome do modelo numa constante, pra trocar de provider mudando uma linha. Aqui uso generateText do AI SDK, exatamente como a doc mostra, passando o modelo no formato provider/modelo:

import { generateText } from 'ai';

// Troca de provider = trocar esta string. Confira os nomes no Browse models.
const MODEL = 'anthropic/claude-opus-5'; // ex.: 'xai/grok-4.5', 'openai/gpt-5.6-sol'

export async function POST(req: Request) {
  const { prompt } = await req.json();
  const start = performance.now();

  const { text } = await generateText({
    model: MODEL,
    prompt,
  });

  const latencyMs = Math.round(performance.now() - start);
  return Response.json({ text, latencyMs, model: MODEL });
}

Repare que a única coisa acoplada ao provider é a string MODEL. Trocar de provider no catálogo (ou configurar fallback via provider options) não exige mexer no resto. Essa é a real vantagem do Gateway, que a doc resume como "switch between providers and models with minimal code changes": o contrato do meu handler não muda. Os nomes de modelo (anthropic/claude-opus-5, xai/grok-4.5, openai/gpt-5.6-sol) são os que aparecem nos próprios exemplos da doc, então confirme quais estão disponíveis na sua conta pelo Browse models.

E a geração de imagem?

Era o objetivo original da pauta, e aqui preciso ser transparente: a página do AI Gateway que consultei não documenta um endpoint de imagem no exemplo principal. O AI SDK expõe experimental_generateImage, e existe uma página "Image Generation" no mapa de links da doc, mas eu não vou colar aqui um path de API inventado como se fosse oficial, porque isso te faria bater num 404 e culpar o próprio código.

O caminho verificável é o mesmo padrão do handler acima, só trocando a função do SDK por experimental_generateImage depois de confirmar, no seu catálogo, o nome exato do modelo de imagem exposto. A estrutura de "isolar o modelo numa constante e trocar uma linha" continua idêntica. Se você depender disso em produção, valide o nome e o formato de resposta no painel antes, porque catálogo e nomes mudam rápido.

Consumindo no client com feedback

Do lado do componente, o foco é performance percebida: mostrar estado de loading e não travar a UI enquanto o modelo responde. O bug clássico aqui é fazer o fetch e esquecer de setar o estado com o resultado, então a tela nunca atualiza. Presta atenção no setText:

'use client';
import { useState } from 'react';

export default function Gen() {
  const [text, setText] = useState('');
  const [busy, setBusy] = useState(false);
  const [ms, setMs] = useState(0);

  async function run() {
    setBusy(true);
    try {
      const r = await fetch('/api/gen', {
        method: 'POST',
        body: JSON.stringify({ prompt: 'Explique HTTP/2 em uma frase' }),
      });
      const d = await r.json();
      setText(d.text); // <- sem isso, nada aparece na tela
      setMs(d.latencyMs);
    } finally {
      setBusy(false);
    }
  }

  return (
    <div>
      <button onClick={run} aria-busy={busy} disabled={busy}>
        {busy ? 'Gerando...' : 'Gerar'}
      </button>
      {text && <p>{text}</p>}
      {ms > 0 && <p>Latência: {ms}ms</p>}
    </div>
  );
}

Detalhe de acessibilidade↳Acessibilidade11 conteúdosO que é Acessibilidade Web e como tornar seu site mais acessívelDev (Back & Front) · mar 2019Design para veteranos digitais: acessibilidade para nós mesmosProduto & UX · jan 2020Dicas de Front-End para usabilidade, acessibilidade, performance e responsividadeProduto & UX · fev 2025Ver tudo em Produto & UX → que costuma faltar em demos de IA: o aria-busy no botão comunica o estado a leitores de tela, já que a espera é longa, e o disabled evita disparos duplicados. Se você adaptar isso para imagem, lembre de dar um alt que descreva o conteúdo real (o prompt já te dá isso de graça), não um genérico "imagem gerada".

Medindo antes e depois

Minha medição foi simples de propósito: cronometrar a chamada com performance.now() no servidor e devolver latencyMs no JSON. Não confie em "achismo" de qual provider é mais rápido; meça no seu ambiente e prompt.

Rodei o mesmo prompt trocando só a constante MODEL. O que vale registrar:

• Latência varia muito por modelo e tamanho de saída. Um prompt que pede resposta curta reduz o tempo de forma visível.
• O painel de Observability do Gateway dá latência e spend agregados por provider, então cruzei minha medição local com o número deles.
• Custo: como a doc afirma zero markup sobre tokens (inclusive com BYOK), a comparação entre providers pelo painel é direta, sem conta paralela.

Vale a pena?

Para quem já está no ecossistema Vercel, o ganho concreto é operacional: uma chave, troca de modelo por string e fallback automático se um provider cai. O código do meu handler não conhece provider nenhum, e isso é ótimo pra testar alternativas sem refatorar. A ressalva honesta fica para imagem: a doc principal do Gateway ainda não expõe isso de forma pronta para copiar e colar, então valide o modelo e o endpoint no Browse models e na página de Image Generation antes de prometer geração de imagem para o seu time.

Fonte: Vercel AI Gateway — Docs