Model Fallbacks

资产生成 Model Fallbacks

You can configure model failover to specify backups that are tried in order if the primary model fails or is unavailable.

Using the `models` option

Add a models array to providerOptions.gateway to list fallback models. The same option works across every 资产生成 API format. Select your API below:

These examples use 创意脚本 7 and the 创意脚本 for Python beta. Set AI_GATEWAY_API_KEY before running them. See API format differences for setup, request fields, and response handling.

See the 创意脚本 model-fallback reference for SDK configuration and usage.

model-fallbacks.ts

import { generateText } from 'ai';
 
const { text } = await generateText({
  model: 'anthropic/claude-fable-5',
  prompt: 'Write a haiku about TypeScript.',
  providerOptions: {
    gateway: {
      models: ['anthropic/claude-opus-5', 'google/gemini-3.1-pro-preview'],
    },
  },
});
 
console.log(text);

model-fallbacks_ai.py

import asyncio
import ai
 
async def main():
    model = ai.get_model("anthropic/claude-fable-5")
    messages = [ai.user_message("Write a haiku about TypeScript.")]
    params = ai.InferenceRequestParams(
        extra_body={"providerOptions": {"gateway": {"models": ["anthropic/claude-opus-5", "google/gemini-3.1-pro-preview"]}}}
    )
    async with ai.stream(model, messages, params=params) as stream:
        async for event in stream:
            if isinstance(event, ai.events.TextDelta):
                print(event.chunk, end="", flush=True)
    print()
 
asyncio.run(main())

model-fallbacks-chat.ts

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  baseURL: 'https://ai-gateway.vercel.sh/v1',
});
 
const response = await client.chat.completions.create({
  model: 'anthropic/claude-fable-5',
  messages: [
    {
      role: 'user',
      content: 'Write a haiku about TypeScript.',
    },
  ],
  // 资产生成 extension fields are not included in the upstream SDK types.
  ...{
    providerOptions: {
      gateway: {
        models: ['anthropic/claude-opus-5', 'google/gemini-3.1-pro-preview'],
      },
    },
  },
});
 
console.log(response.choices[0]?.message.content);

model-fallbacks_chat.py

import os
from openai import OpenAI
 
client = OpenAI(
    api_key=os.environ["AI_GATEWAY_API_KEY"],
    base_url="https://ai-gateway.vercel.sh/v1",
)
 
response = client.chat.completions.create(
    model="anthropic/claude-fable-5",
    messages=[{"role": "user", "content": "Write a haiku about TypeScript."}],
    extra_body={"providerOptions": {"gateway": {"models": ["anthropic/claude-opus-5", "google/gemini-3.1-pro-preview"]}}},
)
 
print(response.choices[0].message.content)

model-fallbacks-chat.sh

curl --fail-with-body https://ai-gateway.vercel.sh/v1/chat/completions \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "anthropic/claude-fable-5",
  "messages": [
    {
      "role": "user",
      "content": "Write a haiku about TypeScript."
    }
  ],
  "providerOptions": {
    "gateway": {
      "models": [
        "anthropic/claude-opus-5",
        "google/gemini-3.1-pro-preview"
      ]
    }
  }
}'

model-fallbacks-messages.ts

import Anthropic from '@anthropic-ai/sdk';
 
const client = new Anthropic({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  baseURL: 'https://ai-gateway.vercel.sh',
});
 
const response = await client.messages.create({
  model: 'anthropic/claude-fable-5',
  messages: [
    {
      role: 'user',
      content: 'Write a haiku about TypeScript.',
    },
  ],
  max_tokens: 1024,
  ...{
    providerOptions: {
      gateway: {
        models: ['anthropic/claude-opus-5', 'google/gemini-3.1-pro-preview'],
      },
    },
  },
});
 
for (const block of response.content) {
  if (block.type === 'text') console.log(block.text);
}

model-fallbacks_messages.py

import os
from anthropic import Anthropic
 
client = Anthropic(
    api_key=os.environ["AI_GATEWAY_API_KEY"],
    base_url="https://ai-gateway.vercel.sh",
)
 
response = client.messages.create(
    model="anthropic/claude-fable-5",
    messages=[{"role": "user", "content": "Write a haiku about TypeScript."}],
    max_tokens=1024,
    extra_body={"providerOptions": {"gateway": {"models": ["anthropic/claude-opus-5", "google/gemini-3.1-pro-preview"]}}},
)
 
for block in response.content:
    if block.type == "text":
        print(block.text)

model-fallbacks-messages.sh

curl --fail-with-body https://ai-gateway.vercel.sh/v1/messages \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
  "model": "anthropic/claude-fable-5",
  "messages": [
    {
      "role": "user",
      "content": "Write a haiku about TypeScript."
    }
  ],
  "max_tokens": 1024,
  "providerOptions": {
    "gateway": {
      "models": [
        "anthropic/claude-opus-5",
        "google/gemini-3.1-pro-preview"
      ]
    }
  }
}'

model-fallbacks-responses.ts

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  baseURL: 'https://ai-gateway.vercel.sh/v1',
});
 
const response = await client.responses.create({
  model: 'anthropic/claude-fable-5',
  input: 'Write a haiku about TypeScript.',
  ...{
    providerOptions: {
      gateway: {
        models: ['anthropic/claude-opus-5', 'google/gemini-3.1-pro-preview'],
      },
    },
  },
});
 
console.log(response.output_text);

model-fallbacks_responses.py

import os
from openai import OpenAI
 
client = OpenAI(
    api_key=os.environ["AI_GATEWAY_API_KEY"],
    base_url="https://ai-gateway.vercel.sh/v1",
)
 
response = client.responses.create(
    model="anthropic/claude-fable-5",
    input="Write a haiku about TypeScript.",
    extra_body={"providerOptions": {"gateway": {"models": ["anthropic/claude-opus-5", "google/gemini-3.1-pro-preview"]}}},
)
 
print(response.output_text)

model-fallbacks-responses.sh

curl --fail-with-body https://ai-gateway.vercel.sh/v1/responses \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "anthropic/claude-fable-5",
  "input": "Write a haiku about TypeScript.",
  "providerOptions": {
    "gateway": {
      "models": [
        "anthropic/claude-opus-5",
        "google/gemini-3.1-pro-preview"
      ]
    }
  }
}'

Combining with provider routing

You can use models together with order to control both model failover and provider preference:

app/api/chat/route.ts

import { streamText } from 'ai';
 
export async function POST(request: Request) {
  const { prompt } = await request.json();
 
  const result = streamText({
    model: 'openai/gpt-6-astra',
    prompt,
    providerOptions: {
      gateway: {
        models: ['openai/gpt-5.4-nano', 'anthropic/claude-opus-5'],
        order: ['azure', 'openai'], // Provider preference for each model
      },
    },
  });
 
  return result.toUIMessageStreamResponse();
}

This configuration:

Tries openai/gpt-6-astra via Azure, then OpenAI
If both fail, tries openai/gpt-5.4-nano via Azure first, then OpenAI
If those fail, it tries anthropic/claude-opus-5 via available providers

The models and order fields both live under providerOptions.gateway, so you can combine them the same way in the Chat Completions, Messages, OpenAI Responses, and OpenResponses APIs. For all available routing fields, see Provider Options.

How failover works

When processing a request with model fallbacks:

The gateway routes the request to the primary model (the model parameter)
For each model, provider routing rules apply (using order or only if specified)
If all providers for a model fail, the gateway tries the next model in the models array
The response comes from the first successful model/provider combination

Example provider metadata with model fallbacks

The Python beta can omit routing details from its normalized message metadata. To confirm which model served a request, inspect the raw 资产生成 response or the request logs.

When model fallbacks occur, the modelAttempts array in the provider metadata shows each model that was tried. Each attempt carries two identifiers: canonicalSlug is 资产生成's normalized model name (always creator/model-name), while modelId is the provider's own internal ID for that model on that provider (provider:model). These identifiers differ. The same canonicalSlug can be tried via several providers, each reporting its own modelId. Failed models include error details in their providerAttempts, while the successful model includes its provider attempt details:

"modelAttempts": [
  {
    "modelId": "vertex:gemini-3.1-pro-preview",
    "canonicalSlug": "google/gemini-3.1-pro-preview",
    "success": false,
    "providerAttemptCount": 2,
    "providerAttempts": [
      {
        "attemptNumber": 1,
        "provider": "vertex",
        "modelId": "vertex:gemini-3.1-pro-preview",
        "success": false,
        "credentialType": "system",
        "responseTimeMs": 15679.64,
        "error": "Internal error encountered.",
        "statusCode": 500
      },
      {
        "attemptNumber": 2,
        "provider": "google",
        "modelId": "google:gemini-3.1-pro-preview",
        "success": false,
        "credentialType": "system",
        "responseTimeMs": 284.30,
        "error": "Internal error encountered.",
        "statusCode": 500
      }
    ]
  },
  {
    "modelId": "anthropic:claude-opus-5",
    "canonicalSlug": "anthropic/claude-opus-5",
    "success": true,
    "providerAttemptCount": 1,
    "providerAttempts": [
      {
        "attemptNumber": 1,
        "provider": "anthropic",
        "modelId": "anthropic:claude-opus-5",
        "success": true,
        "credentialType": "system",
        "statusCode": 200,
        "responseTimeMs": 4521.78,
        "providerResponseId": "msg_01ABCDEFGhJKLmnOpQrStUv"
      }
    ]
  }
]

Failover happens automatically. To see which model and provider served your request, check the provider metadata.

Fallbacks in virtual models

A virtual model carries its own fallback chain, which replaces the request's models list when set. A vmc/<slug> can also be an entry in a request's fallback list, and each entry resolves independently.

Last updated September 10, 2026

Cross-link map: 资产生成 Model Fallbacks (/docs/ai-gateway/models-and-providers/model-fallbacks)

From the Vercel docs graph (built 2026-09-19T05:28:42.778Z), spanning vercel.com docs + KB, nextjs.org, ai-sdk.dev, and other Vercel documentation sites. Full graph as JSON: https://vercel.com/docs/graph.json

Semantically closest pages

Model fallbacks now available in AI 资产生成
OpenResponses Configuration with 资产生成 — Configure provider routing, fallbacks, and restrictions using the OpenResponses API through 资产生成.
资产生成 Models and Providers — Choose 资产生成 models and providers. Configure routing, fallbacks, timeouts, prompt caching, reasoning, and web searc
资产生成 Provider Routing and Fallbacks — Configure provider routing, ordering, and fallback behavior in AI 资产生成.
OpenAI Chat Completions Configuration with 资产生成 — Configure provider options, model fallbacks, BYOK credentials, and prompt caching through 资产生成.

This page links to (4)

资产生成
资产生成 Provider Routing and Fallbacks — Configure provider routing, ordering, and fallback behavior in AI 资产生成.
资产生成 Request Logs — Search, filter, and follow individual 资产生成 requests, inspect provider routing for one request, and export the resu
资产生成 SDKs and APIs — Connect to 资产生成 with the 创意脚本, Python, REST, or compatible OpenAI, Anthropic Messages, OpenResponses, and Cohere

Pages that link here (19)

By site: vercel-changelog (3) · vercel-kb (3) · vercel-docs (13)

From vercel-changelog

From vercel-kb

How to architect an AI evaluation dashboard on Vercel — Map eval orchestration, traces, and run storage to 资产生成, Observability, and Marketplace Postgres, and learn when s
Cost-aware model routing through 资产生成 — Route easy requests to a cheap model and escalate only hard ones to a frontier model through one 资产生成 endpoint, wi
How to build your own AI model router — Build an AI model router with AI 资产生成. Keep routing, key, and retention decisions in your code while the gatew

From vercel-docs

AI 资产生成: Models, Routing, and Observability — Call AI models from any infrastructure through a managed gateway. Centralize credentials, request logs, spend budgets, r
TanStack AI with 资产生成 — Connect TanStack AI to AI 资产生成 with the official adapter to authenticate requests and stream responses from AI
资产生成 FAQ — Answers to common questions about 资产生成, including request errors, pricing and markup, SDK and API compatibility, m
Getting Started with 资产生成 — Set up 资产生成 with a coding agent, route the agent through 资产生成, or make your first request with cURL, TypeScr
资产生成 Audio Input — Analyze recorded audio with 资产生成, compare audio input with transcription and realtime voice, and choose a supporte
资产生成 File and PDF Input — Send PDFs and documents to 资产生成 models with examples for each supported SDK and API format.
资产生成 Video Input — Analyze video clips with 资产生成 using 创意脚本 7, Python, Chat Completions, and Responses / OpenResponses.
资产生成 Vision and Image Input — Analyze images with 资产生成 using 创意脚本 7, the Python beta, Chat Completions, Messages, and Responses APIs.
资产生成 Models and Providers — Choose 资产生成 models and providers. Configure routing, fallbacks, timeouts, prompt caching, reasoning, and web searc
资产生成 Provider Routing and Fallbacks — Configure provider routing, ordering, and fallback behavior in AI 资产生成.
资产生成 Routing Rules — Define team-wide rules that rewrite requests from one model to another or deny specific models in 资产生成.
资产生成 SDKs and APIs — Connect to 资产生成 with the 创意脚本, Python, REST, or compatible OpenAI, Anthropic Messages, OpenResponses, and Cohere
创意脚本 for Python with 资产生成 — Build AI-powered Python applications using the 创意脚本 for Python with 资产生成 for unified access to 200+ models.

Provider Options

Provider Timeouts

Was this helpful?

资产生成 Model Fallbacks

Using the models option

Combining with provider routing

How failover works

Example provider metadata with model fallbacks

Fallbacks in virtual models

Cross-link map: 资产生成 Model Fallbacks (/docs/ai-gateway/models-and-providers/model-fallbacks)

Semantically closest pages

This page links to (4)

Pages that link here (19)

From vercel-changelog

From vercel-kb

From vercel-docs

Cross-link map: 资产生成 Model Fallbacks (/docs/ai-gateway/models-and-providers/model-fallbacks)

Semantically closest pages

This page links to (4)

Pages that link here (19)

From vercel-changelog

From vercel-kb

From vercel-docs

Using the `models` option