Provider Overview and AI Gateway

Purpose and Scope

This page explains the provider entry point that most new AI SDK applications should consider first: Vercel AI Gateway. A provider is the adapter that turns a model choice into an executable AI SDK call. The Gateway provider is different from a single-vendor provider because it connects one AI SDK interface to models from OpenAI, Anthropic, Google, Meta, xAI, and other providers. That means the first design decision is not only which model family to use, but whether the application should access those models through Gateway or through provider-specific packages. Sources: content/providers/01-ai-sdk-providers/00-ai-gateway.mdx

Gateway is documented as part of the AI SDK itself, so it is the lowest-friction path for applications that want provider choice without adding one package per vendor. The source page emphasizes that a plain model string can be enough for most use cases, and that the SDK automatically routes strings in the creator and model name format through AI Gateway. This is why examples can pass a value such as an OpenAI model identifier directly to core generation functions while keeping the same call shape when switching to another provider family. Sources: content/providers/01-ai-sdk-providers/00-ai-gateway.mdx

Relevant Source Files

• content/providers/01-ai-sdk-providers/00-ai-gateway.mdx — Defines the AI Gateway provider page, its feature set, basic usage forms, provider instance behavior, custom provider options, and authentication entry points.

Core Primitives

The first primitive is the model string. In Gateway usage, a model string identifies both the creator and the concrete model name, so the model selection can stay in configuration, request metadata, or application state without importing a vendor-specific provider. This is useful for dashboards, feature flags, per-user model selection, and experiments where the rest of the AI SDK call should remain stable. The same structure applies to text generation, structured output, agents, and UI-backed requests because the model argument is resolved before the underlying model call is executed. Sources: content/providers/01-ai-sdk-providers/00-ai-gateway.mdx

The second primitive is the Gateway provider instance. The documentation shows a default instance exported from the main AI SDK package and notes that this instance is available from version 5.0.36 and later. A provider instance is useful when you want model selection to be explicit in code rather than relying on global string routing. It is also the bridge to more advanced provider management patterns, because an instance can be placed into a provider registry, wrapped with middleware, or configured differently for different areas of an application. Sources: content/providers/01-ai-sdk-providers/00-ai-gateway.mdx

The third primitive is a custom Gateway instance created with a factory. The custom instance exists for cases where default environment-based behavior is not enough. The documented settings include a different API base URL, an API key or Vercel access token, a Vercel team identifier or slug, custom headers, a custom fetch implementation, and a metadata cache refresh interval. These are not model settings; they configure how the provider connects, authenticates, scopes requests, and refreshes Gateway metadata for the process using it. Sources: content/providers/01-ai-sdk-providers/00-ai-gateway.mdx

Basic Usage Patterns

For most applications, the direct model string form is the shortest path. Import a core function, pass a Gateway-compatible model identifier, and keep the rest of the request focused on the prompt, messages, tools, or output mode. This pattern is especially convenient when the application is deployed on Vercel, because the documented Gateway feature list includes automatic authentication in that environment. It also avoids installing additional provider modules for each vendor, which reduces setup complexity when teams are still comparing models or need to support several providers in one product. Sources: content/providers/01-ai-sdk-providers/00-ai-gateway.mdx

import { generateText } from 'ai';
 
const { text } = await generateText({
  model: 'openai/gpt-5.4',
  prompt: 'Hello world',
});

Use the provider instance form when you want the code to make the provider boundary visible. This form imports both the generation function and the Gateway provider from the main package, then calls the provider with the same model identifier. The behavior is still Gateway-backed, but the call site now resembles provider-specific package usage. That can make refactoring easier if a module accepts a provider instance, if tests replace the provider, or if a team wants all model creation to pass through a common factory before requests are made. Sources: content/providers/01-ai-sdk-providers/00-ai-gateway.mdx

import { generateText, gateway } from 'ai';
 
const { text } = await generateText({
  model: gateway('openai/gpt-5.4'),
  prompt: 'Hello world',
});

Provider Packages, Gateway, and When to Choose Each

Gateway is the default overview path when the goal is broad model access with consistent AI SDK code. The documented features call out switching between models and providers, pricing visibility across providers, and observability through the Vercel dashboard. Those capabilities matter when an application is moving from prototype to production because model choice becomes an operational concern, not just a code import. Teams often need to compare latency, quality, cost, and availability. Gateway centralizes that decision while preserving the same high-level AI SDK function calls. Sources: content/providers/01-ai-sdk-providers/00-ai-gateway.mdx

Provider-specific packages are still important when an application needs direct integration with a vendor package, provider-specific authentication behavior, or vendor-specific features that are best represented by that provider module. The Gateway page frames its value as avoiding separate provider integrations, not as removing every reason to use direct providers. A practical rule is to start with Gateway when you want simple multi-provider access, then move a specific workflow to a direct provider package only when a concrete capability, credential model, deployment requirement, or compatibility issue justifies the additional dependency and configuration surface. Sources: content/providers/01-ai-sdk-providers/00-ai-gateway.mdx

Custom Gateway Configuration Reference

Custom configuration is most useful when Gateway is part of an application platform rather than a single route handler. For example, a multi-tenant app may need to scope calls to a Vercel team, attach headers for internal tracing, or provide a controlled fetch wrapper that records outbound request metadata. Tests may use a custom fetch to return deterministic responses. Long-running services may tune metadata refresh behavior so provider and model metadata stay current without refreshing on every request. These settings belong at provider creation time because they affect every model call made through that instance. Sources: content/providers/01-ai-sdk-providers/00-ai-gateway.mdx

import { createGateway } from 'ai';
 
const gateway = createGateway({
  apiKey: process.env.AI_GATEWAY_API_KEY ?? '',
});

Authentication and Deployment Notes

The Gateway documentation describes API key authentication through the AI_GATEWAY_API_KEY environment variable or by passing the key directly into a custom provider instance. It also states that the API key setting can carry AI Gateway API keys, Vercel personal access tokens, and Vercel app access tokens. In deployment, prefer environment variables or platform-managed secrets over hard-coded values. Passing a key directly is useful for examples, tests, or controlled factories, but production code should keep credentials outside source files and centralize provider creation in a small module. Sources: content/providers/01-ai-sdk-providers/00-ai-gateway.mdx

AI_GATEWAY_API_KEY=your_api_key_here

A second deployment concern is team scoping. The team identifier or slug option exists for multi-team Vercel access tokens, where the token alone may not fully describe the intended billing or access context. If a service runs requests for multiple teams, treat provider instances as scoped resources instead of sharing one global instance across every tenant. That makes it easier to reason about authentication, observability, and pricing in the Vercel dashboard, which the Gateway feature list identifies as part of the provider’s production value. Sources: content/providers/01-ai-sdk-providers/00-ai-gateway.mdx

System-to-Code Mapping

Next Steps

Start with Gateway if you are building a new AI SDK application, need access to several providers, or want deployment-time observability through Vercel. Use the plain model string form for the smallest working implementation, then introduce the Gateway provider instance when you need clearer provider boundaries. Create a custom instance when authentication, headers, team scoping, request interception, testing, or registry integration becomes part of the architecture. If a specific provider feature becomes the deciding requirement, compare the relevant provider package page and keep the Gateway-backed path as the default for general model access. Sources: content/providers/01-ai-sdk-providers/00-ai-gateway.mdx