Vercel AI Gateway

AI Gateway exposes models from multiple providers through shared authentication, model IDs, routing, billing, and observability. Model availability, SDK APIs, CLI commands, prices, and product capabilities change frequently. Verify them from current sources before changing code.

Start with current sources

Before implementing:

1. Inspect the project's language, package manager, installed AI SDK version, and existing provider integration.

2. Read the relevant Vercel page under https://vercel.com/docs/ai-gateway. Use the page's .md form when a tool needs Markdown.

3. Fetch the complete live model list. Do not construct model variants by analogy:

   curl -fsSL https://ai-gateway.vercel.sh/v1/models

4. If the code uses the ai package, load the ai-sdk skill when available. Read version-matched docs under node_modules/ai/docs/ and source under node_modules/ai/src/. If the skill is not installed, use those bundled files directly.

5. Run vercel ai-gateway <command> --help before documenting or scripting CLI flags.

The live model endpoint and installed package take precedence over model names or SDK syntax remembered from training data.

Vercel CLI inventory

The vercel ai-gateway command manages gateway resources for the current team. The setup subcommand connects local coding agents; the rest of the CLI covers the jobs that previously required dashboard work:

Use the CLI for credential and spend management when the user is working from a terminal or in CI. Check vercel ai-gateway <command> --help for current flags before scripting; do not copy a flag list from this skill into generated code.

Route the request to the right guide

Read each relevant reference before editing. A task can require more than one.

Choose the integration surface

AI Gateway also supports OpenAI Responses, Anthropic Messages, OpenResponses, Cohere Rerank, embeddings, image and video generation, speech, transcription, realtime sessions, and decisions (formerly evaluation). Modality pages under https://vercel.com/docs/ai-gateway/modalities cover each request shape, including background jobs for long-running video generation. Decisions are available through AI SDK (experimental_decide in ai 7.0.128+, or the deprecated experimental_evaluate alias on earlier AI SDK 7 releases), POST /v1/evaluate, the OpenAI-compatible POST /v1/decisions, and a TypeSafe-compatible API under /typesafe; they are not available through Chat Completions, Responses, or the Anthropic- or Cohere-compatible endpoints. Read references/evaluation.md before choosing a surface. Read the relevant modality or API page instead of translating one request shape from memory.

Minimal AI SDK request

The current AI SDK requires Node.js 22 or later. Confirm the installed package's engines field before enforcing a version in an existing project.

import { generateText } from 'ai';

const model = process.env.AI_GATEWAY_MODEL;
if (!model) {
  throw new Error('Set AI_GATEWAY_MODEL to an ID returned by /v1/models');
}

const { text } = await generateText({
  model,
  prompt: 'Explain the project in one paragraph.',
});

console.log(text);

Honor an exact model the user or task specifies after confirming it exists. Otherwise fetch /v1/models, choose a model that fits the requested modality, capabilities, price, context window, data-retention policy, and team access, and set AI_GATEWAY_MODEL to that ID. Do not put a time-sensitive model recommendation in reusable examples.

Plain model strings route through AI Gateway. Add @ai-sdk/gateway only when the task needs its exported provider, types, model discovery, generation lookup, or spend-report helpers.

Authentication decision

• Use an AI Gateway API key for local scripts, CI, external servers, and non-Vercel deployments. Store it in AI_GATEWAY_API_KEY and never print or commit it.
• Use Vercel OIDC for Vercel deployments and linked local projects. Vercel deployments receive VERCEL_OIDC_TOKEN; local development uses vercel link and vercel env pull.
• BYOK provider credentials do not replace AI Gateway request authentication. They decide how AI Gateway authenticates to a model provider.
• A plain Node.js script does not automatically load .env.local. Export variables in the shell or load that file explicitly. Framework behavior may differ.

Do not ask the user to paste a secret into chat, source code, a committed config file, or a command that will enter shell history unless the repository has an established secure mechanism.

Implementation workflow

1. Establish the user's job, runtime, deployment target, current provider, and required capabilities.
2. Select authentication from the rules above. Preserve a working existing method unless the user asked to migrate it.
3. Fetch live model metadata and choose a compatible model. State why it fits.
4. Read the matching SDK, API, modality, routing, or coding-agent docs.
5. Make the smallest end-to-end change. Reuse the current project structure and error handling.
6. Handle only errors the application can act on. Common gateway outcomes include authentication failure, insufficient credits, budget exhaustion, rate limiting, and provider capacity failure.
7. Run the project's formatter, type checker, and focused tests.
8. When the task authorizes a live request, run one and inspect the returned model, text or media, usage, and provider metadata.
9. Verify the request in AI Gateway Logs when dashboard access is available. Logs can take about 90 seconds to ingest.

Only spend credits, create keys, change budgets, change routing rules, or write coding-agent config when the user requested or approved that outward-facing action. Prefer dry runs and interactive previews when available.

Routing invariants

• Model IDs use the exact provider/model strings returned by /v1/models.
• order controls provider preference, only restricts providers, and sort ranks providers by a supported metric.
• models lists fallback models after the primary model.
• caching: 'auto' manages provider prompt-cache markers. It is not an HTTP response cache.
• providerTimeouts applies to BYOK provider attempts. Streaming requests clear it at the first stream chunk; non-streaming requests time the complete response.
• A reasoning entry in providerOptions overrides the AI SDK top-level reasoning value entirely; the two never merge.
• user and tags attach reporting dimensions. They do not create per-user rate limits.
• Request-scoped provider credentials belong under providerOptions.gateway.byok and must remain secret.
• Virtual Model IDs use vmc/<slug>. A Virtual Model can pin routing and provider options server-side; settings it defines generally override the corresponding request settings, while unset settings remain request-configurable.

Read references/routing.md before adding any of these fields.

Verification checklist

• A direct model ID exists in the full live model response, or a Virtual Model exists for the authenticated team and resolves as vmc/<slug>.
• The selected API or SDK supports the requested modality and feature.
• Authentication works in the actual runtime, including .env.local loading where relevant.
• The example prints or returns a result instead of discarding the response.
• The project type checker and focused tests pass.
• A live request was made only when authorized, and its cost was understood.
• Provider routing or fallback behavior is visible in response metadata or Logs.
• No secret appears in source, logs, diffs, or the final response.
• The final report distinguishes code verification from live and dashboard verification.

Current documentation

• Getting started: https://vercel.com/docs/ai-gateway/getting-started
• Models and providers: https://vercel.com/docs/ai-gateway/models-and-providers
• Virtual Models: https://vercel.com/docs/ai-gateway/models-and-providers/virtual-models
• SDKs and APIs: https://vercel.com/docs/ai-gateway/sdks-and-apis
• Authentication and BYOK: https://vercel.com/docs/ai-gateway/authentication-and-byok
• Observability and spend: https://vercel.com/docs/ai-gateway/observability-and-spend
• Modalities: https://vercel.com/docs/ai-gateway/modalities
• Decision: https://vercel.com/docs/ai-gateway/modalities/decision
• TypeSafe API: https://vercel.com/docs/ai-gateway/sdks-and-apis/typesafe
• REST API reference: https://vercel.com/docs/ai-gateway/sdks-and-apis/rest-api
• FAQ: https://vercel.com/docs/ai-gateway/faq
• Coding agents: https://vercel.com/docs/ai-gateway/coding-agents
• AI SDK provider: https://ai-sdk.dev/providers/ai-sdk-providers/ai-gateway