Backport: feat (provider/gateway): add models provider option for fallbacks (#9758)

This is an automated backport of #9734 to the release-v5.0 branch.

Co-authored-by: Walter Korman <[email protected]>

Author: vercel-ai-sdk[bot]

.changeset/four-papayas-divide.md

@@ -0,0 +1,5 @@
+---
+'@ai-sdk/gateway': patch
+---
+
+feat (provider/gateway): add models provider option for model routing

content/providers/01-ai-sdk-providers/00-ai-gateway.mdx

@@ -348,6 +348,12 @@ The following gateway provider options are available:
 
   Example: `only: ['anthropic', 'vertex']` will only allow routing to Anthropic or Vertex AI.
 
+- **models** _string[]_
+
+  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-nano', 'gemini-2.0-flash']` will try the fallback models in order if the primary model fails.
+
 - **user** _string_
 
   Optional identifier for the end user on whose behalf the request is being made. This is used for spend tracking and attribution purposes, allowing you to track usage per end-user in your application.
@@ -378,6 +384,31 @@ const { text } = await generateText({
 });
 ```
 
+#### Model Fallbacks Example
+
+The `models` option enables automatic fallback to alternative models when the primary model fails:
+
+```ts
+import type { GatewayProviderOptions } from '@ai-sdk/gateway';
+import { generateText } from 'ai';
+
+const { text } = await generateText({
+  model: 'openai/gpt-4o', // Primary model
+  prompt: 'Write a TypeScript haiku',
+  providerOptions: {
+    gateway: {
+      models: ['openai/gpt-5-nano', 'gemini-2.0-flash'], // Fallback models
+    } satisfies GatewayProviderOptions,
+  },
+});
+
+// This will:
+// 1. Try openai/gpt-4o first
+// 2. If it fails, try openai/gpt-5-nano
+// 3. If that fails, try gemini-2.0-flash
+// 4. Return the result from the first model that succeeds
+```
+
 ### Provider-Specific Options
 
 When using provider-specific options through AI Gateway, use the actual provider name (e.g. `anthropic`, `openai`, not `gateway`) as the key:

examples/ai-core/src/stream-text/gateway-provider-options-models.ts

@@ -0,0 +1,32 @@
+import type { GatewayProviderOptions } from '@ai-sdk/gateway';
+import { streamText } from 'ai';
+import 'dotenv/config';
+
+async function main() {
+  const result = streamText({
+    headers: {
+      'X-Simulate-Model-Failures': 'anthropic/claude-4-sonnet',
+    },
+    model: 'anthropic/claude-4-sonnet',
+    prompt: 'Tell me a short tale of the krakens of the deep.',
+    providerOptions: {
+      gateway: {
+        models: ['openai/gpt-5-nano', 'zai/glm-4.6'],
+      } satisfies GatewayProviderOptions,
+    },
+  });
+
+  for await (const textPart of result.textStream) {
+    process.stdout.write(textPart);
+  }
+
+  console.log();
+  console.log(
+    'Provider metadata:',
+    JSON.stringify(await result.providerMetadata, null, 2),
+  );
+  console.log('Token usage:', await result.usage);
+  console.log('Finish reason:', await result.finishReason);
+}
+
+main().catch(console.error);

packages/gateway/src/gateway-provider-options.ts

@@ -35,6 +35,12 @@ const gatewayProviderOptions = lazyValidator(() =>
        * Example: `['chat', 'v2']`
        */
       tags: z.array(z.string()).optional(),
+      /**
+       * Array of model slugs specifying fallback models to use in order.
+       *
+       * Example: `['openai/gpt-5-nano', 'zai/glm-4.6']` will try `openai/gpt-5-nano` first, then `zai/glm-4.6` as fallback.
+       */
+      models: z.array(z.string()).optional(),
     }),
   ),
 );