AI Gateway provider options for routing control
Use providerOptions.gateway to control AI Gateway routing behavior with options: order (string[], sequence of providers to attempt), only (string[], restrict to specified providers only), sort ('cost' | 'ttft' | 'tps', sort providers by metric), models (string[], fallback models if primary fails), user (string, end-user identifier), tags (string[], categorization tags), byok (Record<string, Array<Record<string, unknown>>>, request-scoped BYOK credentials), zeroDataRetention (boolean), disallowPromptTraining (boolean), quotaEntityId (string), has (Array<'implicit-caching' | 'vision'>), providerTimeouts (object), serviceTier ('flex' | 'priority').
AI Gateway order provider option
The order option is a string[] that specifies the sequence of providers to attempt when routing requests. The gateway will try providers in the order specified. If a provider fails or is unavailable, it will move to the next provider in the list. Example: order: ['bedrock', 'anthropic'] will attempt Amazon Bedrock first, then fall back to Anthropic.
AI Gateway only provider option
The only option is a string[] that restricts routing to only the specified providers. When set, the gateway will never route to providers not in this list, even if they would otherwise be available. Example: only: ['anthropic', 'vertex'] will only allow routing to Anthropic or Vertex AI.
AI Gateway sort provider option
The sort option ('cost' | 'ttft' | 'tps') sorts available providers by a performance or cost metric before routing. The gateway will try the best-scoring provider first and fall back through the rest in sorted order. 'cost' = lowest cost first, 'ttft' = lowest time-to-first-token first, 'tps' = highest tokens-per-second first. When combined with order, user-specified providers are promoted to the front. When sort is active, the response's providerMetadata.gateway.routing.sort contains the sort option used, execution order, per-provider metric values, and deprioritized providers.
AI Gateway models fallback option
The models option is a string[] that specifies fallback models to use when the primary model fails or is unavailable. The gateway will try the primary model first (specified in the model parameter), then try each model in this array in order until one succeeds. Example: models: ['openai/gpt-5.4-nano', 'gemini-3-flash-preview'].
AI Gateway user provider option
The user option is a string that identifies the end user on whose behalf the request is being made. Used for spend tracking and attribution purposes, allowing you to track usage per end-user in your application. Example: user: 'user-123' will associate the request with end-user ID 'user-123' in usage reports.
AI Gateway tags provider option
The tags option is a string[] for categorizing and filtering usage in reports. Useful for tracking spend by feature, prompt version, or any other dimension relevant to your application. Example: tags: ['chat', 'v2'] will tag the request with 'chat' and 'v2' for filtering in usage analytics.
AI Gateway byok provider option
The byok option is Record<string, Array<Record<string, unknown>>> for request-scoped BYOK (Bring Your Own Key) credentials. When provided, any cached BYOK credentials configured in the gateway system are not considered. Each provider can have multiple credentials (tried in order). Each credential can optionally include a modelMappings array to map AI Gateway model slugs to your deployment names.
AI Gateway byok provider option examples
BYOK examples: Single provider: byok: { 'anthropic': [{ apiKey: 'sk-ant-...' }] }. Multiple credentials: byok: { 'vertex': [{ project: 'proj-1', googleCredentials: { privateKey: '...', clientEmail: '...' } }, { project: 'proj-2', googleCredentials: { privateKey: '...', clientEmail: '...' } }] }. Multiple providers: byok: { 'anthropic': [{ apiKey: '...' }], 'bedrock': [{ accessKeyId: '...', secretAccessKey: '...' }] }. With model mappings: byok: { 'azure': [{ apiKey: '...', resourceName: '...', modelMappings: [{ gatewayModelSlug: 'openai/gpt-5.4-nano', customModelId: 'my-deployment' }] }] }.
AI Gateway zeroDataRetention provider option
The zeroDataRetention option (boolean) restricts routing to providers with zero data retention agreements with Vercel for AI Gateway. BYOK credentials are skipped by default since your provider agreements differ from Vercel's. When true, AI Gateway routes only to providers Vercel has ZDR agreements with for the model. If you have BYOK keys marked as ZDR, those are tried first, then AI Gateway falls back to system credentials. Request-level ZDR is only available for Vercel Pro and Enterprise plans. If no ZDR-eligible credentials are available, the request fails.
AI Gateway disallowPromptTraining provider option
The disallowPromptTraining option (boolean) restricts routing to providers that have agreements with Vercel for AI Gateway to not use prompts for model training. When using BYOK credentials, this filter is not applied. If BYOK credentials fail and the request falls back to system credentials, only providers that do not train on prompt data will be used. If there are no providers available for the model that disallow prompt training, the request will fail.
AI Gateway quotaEntityId provider option
The quotaEntityId option (string) is the unique identifier for the entity against which quota is tracked. Used for quota management and enforcement purposes. Useful for multi-tenant applications where you need to manage quota at the entity level (e.g., per organization or team).
AI Gateway has provider option
The has option is Array<'implicit-caching' | 'vision'> that restricts routing to provider models with all specified capabilities. Applies to both BYOK and system credentials. Supported capabilities: 'implicit-caching' (models that perform automatic prompt caching), 'vision' (models that accept image input). If no provider model satisfies the capabilities, the request fails.
AI Gateway providerTimeouts provider option
The providerTimeouts option (object) sets per-provider timeouts for BYOK credentials in milliseconds. Controls how long to wait for a provider to start responding before falling back to the next available provider. Example: providerTimeouts: { byok: { openai: 5000, anthropic: 2000 } }.
AI Gateway serviceTier provider option
The serviceTier option ('flex' | 'priority') is a unified service tier intent. The gateway translates it into whichever per-provider option each provider expects and overrides any tier also set in the per-provider options. Leave unset for provider default. See OpenAI, Google Generative AI, and Google Vertex AI provider docs for tier semantics, model availability, and graceful downgrade behavior.
AI Gateway provider-specific options usage
When using provider-specific options through AI Gateway, use the actual provider name (e.g., 'anthropic', 'openai', not 'gateway') as the key in providerOptions. This works with any provider supported by AI Gateway. Each provider has its own set of options - see individual provider documentation pages for details.
AI Gateway example: provider-specific options
Example showing provider-specific options through AI Gateway: import type { AnthropicLanguageModelOptions } from '@ai-sdk/anthropic'; import type { GatewayProviderOptions } from '@ai-sdk/gateway'; import { generateText } from 'ai'; const { text } = await generateText({ model: 'anthropic/claude-sonnet-4.6', prompt: 'Explain quantum computing', providerOptions: { gateway: { order: ['vertex', 'anthropic'], } satisfies GatewayProviderOptions, anthropic: { thinking: { type: 'enabled', budgetTokens: 12000 }, } satisfies AnthropicLanguageModelOptions, }, });
AI Gateway example: model fallbacks
Example showing model fallbacks: import type { GatewayProviderOptions } from '@ai-sdk/gateway'; import { generateText } from 'ai'; const { text } = await generateText({ model: 'openai/gpt-5.4', prompt: 'Write a TypeScript haiku', providerOptions: { gateway: { models: ['openai/gpt-5.4-nano', 'gemini-3-flash-preview'], } satisfies GatewayProviderOptions, }, }); // This will: 1. Try openai/gpt-5.4 first, 2. If it fails, try openai/gpt-5.4-nano, 3. If that fails, try gemini-3-flash-preview, 4. Return the result from the first model that succeeds
AI Gateway example: zero data retention option
Example using zero data retention: import type { GatewayProviderOptions } from '@ai-sdk/gateway'; import { generateText } from 'ai'; const { text } = await generateText({ model: 'anthropic/claude-sonnet-4.6', prompt: 'Analyze this sensitive document...', providerOptions: { gateway: { zeroDataRetention: true, } satisfies GatewayProviderOptions, }, });
AI Gateway example: disallow prompt training option
Example using disallow prompt training: import type { GatewayProviderOptions } from '@ai-sdk/gateway'; import { generateText } from 'ai'; const { text } = await generateText({ model: 'anthropic/claude-sonnet-4.6', prompt: 'Analyze this proprietary business data...', providerOptions: { gateway: { disallowPromptTraining: true, } satisfies GatewayProviderOptions, }, });
AI Gateway example: quota entity ID option
Example using quota entity ID: import type { GatewayProviderOptions } from '@ai-sdk/gateway'; import { generateText } from 'ai'; const { text } = await generateText({ model: 'anthropic/claude-sonnet-4.6', prompt: 'Summarize this report...', providerOptions: { gateway: { quotaEntityId: 'org-123', } satisfies GatewayProviderOptions, }, });
AI Gateway example: filtering by model capability
Example filtering by model capability: import type { GatewayProviderOptions } from '@ai-sdk/gateway'; import { generateText } from 'ai'; const { text } = await generateText({ model: 'openai/gpt-5.5', prompt: 'Summarize this report...', providerOptions: { gateway: { has: ['implicit-caching'], } satisfies GatewayProviderOptions, }, });
AI Gateway example: filtering vision models
Example filtering for vision models: import type { GatewayProviderOptions } from '@ai-sdk/gateway'; import { generateText } from 'ai'; import fs from 'node:fs'; const { text } = await generateText({ model: 'anthropic/claude-sonnet-4.6', messages: [ { role: 'user', content: [ { type: 'text', text: 'Describe the image in detail.' }, { type: 'file', mediaType: 'image/png', data: fs.readFileSync('./data/comic-cat.png'), }, ], }, ], providerOptions: { gateway: { has: ['vision'], } satisfies GatewayProviderOptions, }, });