@ai-sdk/gateway 3.0.218 → 3.0.220

package/docs/00-ai-gateway.mdx

@@ -889,7 +889,7 @@ for await (const part of result.stream) {
 
 #### Parallel Search
 
-The Parallel Search tool enables models to search the web using [Parallel AI's Search API](https://docs.parallel.ai/api-reference/search-beta/search). This tool is optimized for LLM consumption, returning relevant excerpts from web pages that can replace multiple keyword searches with a single call.
+The Parallel Search tool enables models to search the web using [Parallel AI's Search API](https://docs.parallel.ai/api-reference/search/search). The model provides a research objective and a few keyword queries, and the tool returns relevant excerpts from web pages, optimized for LLM consumption.
 
 ```ts
 import { gateway, generateText } from "ai";
@@ -917,7 +917,8 @@ const result = await generateText({
   prompt: "Find detailed information about TypeScript 5.0 features.",
   tools: {
     parallel_search: gateway.tools.parallelSearch({
-      mode: "agentic",
+      mode: "advanced",
+      location: "us",
       maxResults: 5,
       sourcePolicy: {
         includeDomains: ["typescriptlang.org", "github.com"],
@@ -936,12 +937,16 @@ console.log("Tool results:", JSON.stringify(result.toolResults, null, 2));
 
 The Parallel Search tool supports the following optional configuration options:
 
-- **mode** _'one-shot' | 'agentic'_
+- **mode** _'turbo' | 'fast' | 'basic' | 'advanced'_
 
-  Mode preset for different use cases:
+  Search mode. Defaults to `'basic'`. See the [AI Gateway web search docs](https://vercel.com/docs/ai-gateway/models-and-providers/web-search#using-parallel-search) for pricing.
 
-  - `'one-shot'` - Comprehensive results with longer excerpts for single-response answers (default)
-  - `'agentic'` - Concise, token-efficient results optimized for multi-step agentic workflows
+  - `'turbo'` - Lowest latency, shorter excerpts. Supports English and Japanese only.
+  - `'fast'` - Low latency, shorter excerpts.
+  - `'basic'` - Balanced latency and excerpt depth (default).
+  - `'advanced'` - Most thorough retrieval, higher latency.
+
+  `'one-shot'` and `'agentic'` are deprecated but still accepted: `'one-shot'` runs as `'basic'` and `'agentic'` runs as `'advanced'`.
 
 - **maxResults** _number_
 
@@ -951,22 +956,36 @@ The Parallel Search tool supports the following optional configuration options:
 
   Source policy for controlling which domains to include/exclude:
 
-  - `includeDomains` - List of domains to include in search results
-  - `excludeDomains` - List of domains to exclude from search results
-  - `afterDate` - Only include results published after this date (ISO 8601 format)
+  - `includeDomains` - Domains or domain/path prefixes to include, such as `'wikipedia.org'` or `'docs.python.org/3'`. When set, `excludeDomains` is ignored.
+  - `excludeDomains` - Domains or domain/path prefixes to exclude
+  - `afterDate` - Only include results published on or after this date (`YYYY-MM-DD`)
+
+  The include and exclude lists can hold up to 200 entries combined.
+
+- **maxCharsTotal** _number_
+
+  Maximum total characters across all result excerpts.
 
 - **excerpts** _object_
 
   Excerpt configuration for controlling result length:
 
   - `maxCharsPerResult` - Maximum characters per result
-  - `maxCharsTotal` - Maximum total characters across all results
+  - `maxCharsTotal` - Deprecated; use the top-level `maxCharsTotal`
 
 - **fetchPolicy** _object_
 
   Fetch policy for controlling content freshness:
 
-  - `maxAgeSeconds` - Maximum age in seconds for cached content (set to 0 for always fresh)
+  - `maxAgeSeconds` - Maximum age of cached content, in seconds, before a live fetch is attempted. Minimum 600; lower values are raised to 600.
+  - `timeoutSeconds` - Timeout for a live fetch, in seconds. The gateway caps it to stay within its own tool timeout.
+  - `disableCacheFallback` - Return an error instead of older cached content when a live fetch fails. Defaults to `false`.
+
+- **location** _string_
+
+  ISO 3166-1 alpha-2 country code to localize results, such as `'us'`. Invalid codes are ignored with a warning.
+
+Each tool result contains a `search_id` and `results`, ordered by decreasing relevance, and may include a `session_id`. Each result has a `url`, a `title`, a `publish_date` (both may be `null`), and `excerpts` (an array of markdown strings). The result can also include `warnings`, for example when an invalid `location` is ignored.
 
 The tool works with both `generateText` and `streamText`:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-sdk/gateway",
   "private": false,
-  "version": "3.0.218",
+  "version": "3.0.220",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -32,7 +32,7 @@
   "dependencies": {
     "@vercel/oidc": "3.2.0",
     "@ai-sdk/provider": "3.0.19",
-    "@ai-sdk/provider-utils": "4.0.61"
+    "@ai-sdk/provider-utils": "4.0.62"
   },
   "devDependencies": {
     "@types/node": "18.15.11",

package/src/gateway-embedding-model.ts

@@ -97,29 +97,30 @@ export class GatewayEmbeddingModel implements EmbeddingModelV3 {
   }
 }
 
-const gatewayEmbeddingWarningSchema = z.discriminatedUnion('type', [
-  z.object({
-    type: z.literal('unsupported'),
-    feature: z.string(),
-    details: z.string().optional(),
-  }),
-  z.object({
-    type: z.literal('compatibility'),
-    feature: z.string(),
-    details: z.string().optional(),
-  }),
-  z.object({
-    type: z.literal('other'),
-    message: z.string(),
-  }),
-]);
+const gatewayEmbeddingWarningSchema = () =>
+  z.discriminatedUnion('type', [
+    z.object({
+      type: z.literal('unsupported'),
+      feature: z.string(),
+      details: z.string().optional(),
+    }),
+    z.object({
+      type: z.literal('compatibility'),
+      feature: z.string(),
+      details: z.string().optional(),
+    }),
+    z.object({
+      type: z.literal('other'),
+      message: z.string(),
+    }),
+  ]);
 
 const gatewayEmbeddingResponseSchema = lazySchema(() =>
   zodSchema(
     z.object({
       embeddings: z.array(z.array(z.number())),
       usage: z.object({ tokens: z.number() }).nullish(),
-      warnings: z.array(gatewayEmbeddingWarningSchema).optional(),
+      warnings: z.array(gatewayEmbeddingWarningSchema()).optional(),
       providerMetadata: z
         .record(z.string(), z.record(z.string(), z.unknown()))
         .optional(),

package/src/gateway-image-model.ts

@@ -4,6 +4,8 @@ import type {
   ImageModelV3ProviderMetadata,
 } from '@ai-sdk/provider';
 import {
+  lazySchema,
+  zodSchema,
   combineHeaders,
   convertUint8ArrayToBase64,
   createJsonErrorResponseHandler,
@@ -135,46 +137,53 @@ function maybeEncodeImageFile(file: ImageModelV3File) {
   return file;
 }
 
-const providerMetadataEntrySchema = z
-  .object({
-    images: z.array(z.unknown()).optional(),
-  })
-  .catchall(z.unknown());
+const providerMetadataEntrySchema = () =>
+  z
+    .object({
+      images: z.array(z.unknown()).optional(),
+    })
+    .catchall(z.unknown());
 
-const gatewayImageWarningSchema = z.discriminatedUnion('type', [
-  z.object({
-    type: z.literal('unsupported'),
-    feature: z.string(),
-    details: z.string().optional(),
-  }),
-  z.object({
-    type: z.literal('compatibility'),
-    feature: z.string(),
-    details: z.string().optional(),
-  }),
-  z.object({
-    type: z.literal('deprecated'),
-    setting: z.string(),
-    message: z.string(),
-  }),
-  z.object({
-    type: z.literal('other'),
-    message: z.string(),
-  }),
-]);
+const gatewayImageWarningSchema = () =>
+  z.discriminatedUnion('type', [
+    z.object({
+      type: z.literal('unsupported'),
+      feature: z.string(),
+      details: z.string().optional(),
+    }),
+    z.object({
+      type: z.literal('compatibility'),
+      feature: z.string(),
+      details: z.string().optional(),
+    }),
+    z.object({
+      type: z.literal('deprecated'),
+      setting: z.string(),
+      message: z.string(),
+    }),
+    z.object({
+      type: z.literal('other'),
+      message: z.string(),
+    }),
+  ]);
 
-const gatewayImageUsageSchema = z.object({
-  inputTokens: z.number().nullish(),
-  outputTokens: z.number().nullish(),
-  totalTokens: z.number().nullish(),
-});
+const gatewayImageUsageSchema = () =>
+  z.object({
+    inputTokens: z.number().nullish(),
+    outputTokens: z.number().nullish(),
+    totalTokens: z.number().nullish(),
+  });
 
-const gatewayImageResponseSchema = z.object({
-  images: z.array(z.string()), // Always base64 strings over the wire
-  isRetryable: z.boolean().optional(),
-  warnings: z.array(gatewayImageWarningSchema).optional(),
-  providerMetadata: z
-    .record(z.string(), providerMetadataEntrySchema)
-    .optional(),
-  usage: gatewayImageUsageSchema.optional(),
-});
+const gatewayImageResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      images: z.array(z.string()), // Always base64 strings over the wire
+      isRetryable: z.boolean().optional(),
+      warnings: z.array(gatewayImageWarningSchema()).optional(),
+      providerMetadata: z
+        .record(z.string(), providerMetadataEntrySchema())
+        .optional(),
+      usage: gatewayImageUsageSchema().optional(),
+    }),
+  ),
+);

package/src/gateway-language-model-settings.ts

@@ -113,6 +113,7 @@ export type GatewayModelId =
   | 'google/gemma-4-31b-it'
   | 'inception/mercury-2'
   | 'inception/mercury-2.5'
+  | 'inception/mercury-3'
   | 'inception/mercury-coder-small'
   | 'inclusionai/ling-3.0-flash'
   | 'inclusionai/ling-3.0-flash-fin'
@@ -270,6 +271,8 @@ export type GatewayModelId =
   | 'sakana/fugu-ultra'
   | 'sakana/fugu-ultra-v2'
   | 'sakana/namazu'
+  | 'scaledown/scaledown-extract-1'
+  | 'scaledown/scaledown-summarize-1'
   | 'spacexai/grok-4.1-fast-non-reasoning'
   | 'spacexai/grok-4.1-fast-reasoning'
   | 'spacexai/grok-4.20-multi-agent'
@@ -287,7 +290,6 @@ export type GatewayModelId =
   | 'spacexai/grok-4.6'
   | 'spacexai/grok-4.7'
   | 'spacexai/grok-build-0.1'
-  | 'stealth/cat-jam'
   | 'stealth/glyph-cluster'
   | 'stepfun/step-3.7-flash'
   | 'stepfun/step-5-preview'

package/src/gateway-reranking-model-settings.ts

@@ -2,6 +2,8 @@ export type GatewayRerankingModelId =
   | 'cohere/rerank-v3.5'
   | 'cohere/rerank-v4-fast'
   | 'cohere/rerank-v4-pro'
+  | 'cohere/rerank-v5-fast'
+  | 'cohere/rerank-v5-pro'
   | 'voyage/rerank-2.5'
   | 'voyage/rerank-2.5-lite'
   | 'voyage/rerank-3'

package/src/gateway-reranking-model.ts

@@ -98,22 +98,23 @@ export class GatewayRerankingModel implements RerankingModelV3 {
   }
 }
 
-const gatewayRerankingWarningSchema = z.discriminatedUnion('type', [
-  z.object({
-    type: z.literal('unsupported'),
-    feature: z.string(),
-    details: z.string().optional(),
-  }),
-  z.object({
-    type: z.literal('compatibility'),
-    feature: z.string(),
-    details: z.string().optional(),
-  }),
-  z.object({
-    type: z.literal('other'),
-    message: z.string(),
-  }),
-]);
+const gatewayRerankingWarningSchema = () =>
+  z.discriminatedUnion('type', [
+    z.object({
+      type: z.literal('unsupported'),
+      feature: z.string(),
+      details: z.string().optional(),
+    }),
+    z.object({
+      type: z.literal('compatibility'),
+      feature: z.string(),
+      details: z.string().optional(),
+    }),
+    z.object({
+      type: z.literal('other'),
+      message: z.string(),
+    }),
+  ]);
 
 const gatewayRerankingResponseSchema = lazySchema(() =>
   zodSchema(
@@ -124,7 +125,7 @@ const gatewayRerankingResponseSchema = lazySchema(() =>
           relevanceScore: z.number(),
         }),
       ),
-      warnings: z.array(gatewayRerankingWarningSchema).optional(),
+      warnings: z.array(gatewayRerankingWarningSchema()).optional(),
       providerMetadata: z
         .record(z.string(), z.record(z.string(), z.unknown()))
         .optional(),

package/src/gateway-speech-model-settings.ts

@@ -9,6 +9,7 @@ export type GatewaySpeechModelId =
   | 'microsoft/mai-voice-2-flash'
   | 'microsoft/mai-voice-2.1'
   | 'microsoft/mai-voice-2.1-flash'
+  | 'mistral/voxtral-mini-tts-3'
   | 'openai/tts-1'
   | 'openai/tts-1-hd'
   | 'spacexai/grok-tts'

package/src/gateway-speech-model.ts

@@ -1,5 +1,7 @@
 import type { SharedV3ProviderMetadata, SpeechModelV3 } from '@ai-sdk/provider';
 import {
+  lazySchema,
+  zodSchema,
   combineHeaders,
   createJsonErrorResponseHandler,
   createJsonResponseHandler,
@@ -108,34 +110,39 @@ export class GatewaySpeechModel implements SpeechModelV3 {
   }
 }
 
-const providerMetadataEntrySchema = z.object({}).catchall(z.unknown());
+const providerMetadataEntrySchema = () => z.object({}).catchall(z.unknown());
 
-const gatewaySpeechWarningSchema = z.discriminatedUnion('type', [
-  z.object({
-    type: z.literal('unsupported'),
-    feature: z.string(),
-    details: z.string().optional(),
-  }),
-  z.object({
-    type: z.literal('compatibility'),
-    feature: z.string(),
-    details: z.string().optional(),
-  }),
-  z.object({
-    type: z.literal('deprecated'),
-    setting: z.string(),
-    message: z.string(),
-  }),
-  z.object({
-    type: z.literal('other'),
-    message: z.string(),
-  }),
-]);
+const gatewaySpeechWarningSchema = () =>
+  z.discriminatedUnion('type', [
+    z.object({
+      type: z.literal('unsupported'),
+      feature: z.string(),
+      details: z.string().optional(),
+    }),
+    z.object({
+      type: z.literal('compatibility'),
+      feature: z.string(),
+      details: z.string().optional(),
+    }),
+    z.object({
+      type: z.literal('deprecated'),
+      setting: z.string(),
+      message: z.string(),
+    }),
+    z.object({
+      type: z.literal('other'),
+      message: z.string(),
+    }),
+  ]);
 
-const gatewaySpeechResponseSchema = z.object({
-  audio: z.string(),
-  warnings: z.array(gatewaySpeechWarningSchema).optional(),
-  providerMetadata: z
-    .record(z.string(), providerMetadataEntrySchema)
-    .optional(),
-});
+const gatewaySpeechResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      audio: z.string(),
+      warnings: z.array(gatewaySpeechWarningSchema()).optional(),
+      providerMetadata: z
+        .record(z.string(), providerMetadataEntrySchema())
+        .optional(),
+    }),
+  ),
+);

package/src/gateway-transcription-model-settings.ts

@@ -4,6 +4,8 @@ export type GatewayTranscriptionModelId =
   | 'google/gemini-3.5-transcribe-live'
   | 'microsoft/mai-transcribe-2'
   | 'microsoft/mai-transcribe-2-streaming'
+  | 'mistral/voxtral-mini-transcribe-3'
+  | 'mistral/voxtral-small-transcribe-3'
   | 'openai/gpt-4o-mini-transcribe'
   | 'openai/gpt-4o-transcribe'
   | 'openai/gpt-realtime-whisper'

package/src/gateway-transcription-model.ts

@@ -3,6 +3,8 @@ import type {
   TranscriptionModelV3,
 } from '@ai-sdk/provider';
 import {
+  lazySchema,
+  zodSchema,
   combineHeaders,
   convertUint8ArrayToBase64,
   createJsonErrorResponseHandler,
@@ -110,45 +112,50 @@ export class GatewayTranscriptionModel implements TranscriptionModelV3 {
   }
 }
 
-const providerMetadataEntrySchema = z.object({}).catchall(z.unknown());
+const providerMetadataEntrySchema = () => z.object({}).catchall(z.unknown());
 
-const gatewayTranscriptionWarningSchema = z.discriminatedUnion('type', [
-  z.object({
-    type: z.literal('unsupported'),
-    feature: z.string(),
-    details: z.string().optional(),
-  }),
-  z.object({
-    type: z.literal('compatibility'),
-    feature: z.string(),
-    details: z.string().optional(),
-  }),
-  z.object({
-    type: z.literal('deprecated'),
-    setting: z.string(),
-    message: z.string(),
-  }),
-  z.object({
-    type: z.literal('other'),
-    message: z.string(),
-  }),
-]);
+const gatewayTranscriptionWarningSchema = () =>
+  z.discriminatedUnion('type', [
+    z.object({
+      type: z.literal('unsupported'),
+      feature: z.string(),
+      details: z.string().optional(),
+    }),
+    z.object({
+      type: z.literal('compatibility'),
+      feature: z.string(),
+      details: z.string().optional(),
+    }),
+    z.object({
+      type: z.literal('deprecated'),
+      setting: z.string(),
+      message: z.string(),
+    }),
+    z.object({
+      type: z.literal('other'),
+      message: z.string(),
+    }),
+  ]);
 
-const gatewayTranscriptionResponseSchema = z.object({
-  text: z.string(),
-  segments: z
-    .array(
-      z.object({
-        text: z.string(),
-        startSecond: z.number(),
-        endSecond: z.number(),
-      }),
-    )
-    .optional(),
-  language: z.string().nullish(),
-  durationInSeconds: z.number().nullish(),
-  warnings: z.array(gatewayTranscriptionWarningSchema).optional(),
-  providerMetadata: z
-    .record(z.string(), providerMetadataEntrySchema)
-    .optional(),
-});
+const gatewayTranscriptionResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      text: z.string(),
+      segments: z
+        .array(
+          z.object({
+            text: z.string(),
+            startSecond: z.number(),
+            endSecond: z.number(),
+          }),
+        )
+        .optional(),
+      language: z.string().nullish(),
+      durationInSeconds: z.number().nullish(),
+      warnings: z.array(gatewayTranscriptionWarningSchema()).optional(),
+      providerMetadata: z
+        .record(z.string(), providerMetadataEntrySchema())
+        .optional(),
+    }),
+  ),
+);