Provider Options

AI Gateway can route your AI model requests across multiple AI providers. Each provider offers different models, pricing, and performance characteristics. By default, Vercel AI Gateway dynamically chooses the default providers to give you the best experience based on a combination of recent uptime and latency.

With the Gateway Provider Options however, you have control over the routing order and fallback behavior of the models.

You can use order and only in providerOptions.gateway to control which providers handle your requests and in what order.

providerOptions: {
  gateway: {
    order: ['bedrock', 'anthropic'], // Try Bedrock first, then Anthropic
    only: ['bedrock', 'anthropic'],  // Only allow these two providers
  },
},

For full details, examples, and provider metadata output, see Provider Filtering & Ordering.

You can use caching: 'auto' in providerOptions.gateway to let AI Gateway automatically apply the appropriate caching strategy based on the provider. This is useful for providers like Anthropic and MiniMax that require explicit cache markers.

providerOptions: {
  gateway: {
    caching: 'auto',
  },
},

For full details, supported providers, and examples across all APIs, see Automatic Caching.

You can set per-provider timeouts to trigger fast failover when a provider is slow to respond. See the dedicated Provider Timeouts documentation.

For model-level failover strategies that try backup models when your primary model fails or is unavailable, see the dedicated Model Fallbacks documentation.

You can combine AI Gateway provider options with provider-specific options. This allows you to control both the routing behavior and provider-specific settings in the same request:

import { streamText } from 'ai';
 
export async function POST(request: Request) {
  const { prompt } = await request.json();
 
  const result = streamText({
    model: 'anthropic/claude-sonnet-4.6',
    prompt,
    providerOptions: {
      anthropic: {
        thinkingBudget: 0.001,
      },
      gateway: {
        order: ['vertex'],
      },
    },
  });
 
  return result.toUIMessageStreamResponse();
}

In this example:

• We're using an Anthropic model (e.g. Claude 4 Sonnet) but accessing it through Vertex AI
• The Anthropic-specific options still apply to the model:
  • thinkingBudget sets a cost limit of $0.001 per request for the Claude model
• You can read more about provider-specific options in the AI SDK documentation

You can pass your own provider credentials on a per-request basis using the byok option in providerOptions.gateway. This allows you to use your existing provider accounts for specific requests without configuring credentials in the dashboard.

import { streamText } from 'ai';
 
export async function POST(request: Request) {
  const { prompt } = await request.json();
 
  const result = streamText({
    model: 'anthropic/claude-sonnet-4.6',
    prompt,
    providerOptions: {
      gateway: {
        byok: {
          anthropic: [{ apiKey: process.env.ANTHROPIC_API_KEY }],
        },
      },
    },
  });
 
  return result.toUIMessageStreamResponse();
}

For detailed information about credential structures, multiple credentials, and usage with the Chat Completions API, see the BYOK documentation.

For models that support reasoning (also known as "thinking"), you can use providerOptions to configure reasoning behavior. The example below shows how to control the computational effort and summary detail level when using OpenAI's gpt-oss-120b model.

For more details on reasoning support across different models and providers, see the AI SDK providers documentation, including OpenAI, DeepSeek, and Anthropic.

import { streamText } from 'ai';
 
export async function POST(request: Request) {
  const { prompt } = await request.json();
 
  const result = streamText({
    model: 'openai/gpt-oss-120b',
    prompt,
    providerOptions: {
      openai: {
        reasoningEffort: 'high',
        reasoningSummary: 'detailed',
      },
    },
  });
 
  return result.toUIMessageStreamResponse();
}

Note: For openai/gpt-5 and openai/gpt-5.1 models, you must set both reasoningEffort and reasoningSummary in providerOptions to receive reasoning output.

providerOptions: {
  openai: {
    reasoningEffort: 'high', // or 'minimal', 'low', 'medium', 'none'
    reasoningSummary: 'detailed', // or 'auto', 'concise'
  },
}

You can view the available models for a provider in the Model List section under the AI Gateway section in your Vercel dashboard sidebar or in the public models page.