@ai-sdk/gateway 4.0.0-canary.98 → 4.0.0

package/docs/00-ai-gateway.mdx

@@ -235,6 +235,98 @@ console.log(ranking);
 
 Reranking models are useful for improving search results in retrieval-augmented generation (RAG) pipelines by re-scoring candidate documents after an initial retrieval step.
 
+## Realtime Models
+
+<Note type="warning">
+  Realtime support is experimental and the API may change in patch releases.
+</Note>
+
+You can create realtime models for bidirectional audio/text WebSocket sessions using the `experimental_realtime` method on the provider instance. The first argument is the model ID in the format `creator/model-name`:
+
+```ts
+import { gateway } from '@ai-sdk/gateway';
+
+const model = gateway.experimental_realtime('openai/gpt-realtime-2');
+```
+
+The Gateway normalizes realtime the same way it normalizes every other modality: your client speaks the [normalized AI SDK realtime protocol](/docs/ai-sdk-core/realtime) and the Gateway translates to and from the upstream provider server-side. This means the same client code works regardless of which provider backs the model.
+
+Realtime sessions run in the browser and require a short-lived Gateway client secret created on your server with `gateway.experimental_realtime.getToken()`. The method uses your Gateway credential (`apiKey`, `AI_GATEWAY_API_KEY`, or Vercel OIDC token) to mint a `vcst_` client secret and returns the WebSocket URL for the model.
+
+```ts filename='app/api/realtime/setup/route.ts'
+import { gateway } from 'ai';
+
+export async function POST() {
+  const token = await gateway.experimental_realtime.getToken({
+    model: 'openai/gpt-realtime-2',
+    expiresAfterSeconds: 60 * 10,
+  });
+
+  return Response.json(token);
+}
+```
+
+Use the matching Gateway realtime model in the browser. Creating the model is
+safe in browser code; only `getToken()` is server-side.
+
+```tsx filename='app/realtime/page.tsx'
+'use client';
+
+import { experimental_useRealtime } from '@ai-sdk/react';
+import { gateway } from 'ai';
+
+export default function RealtimePage() {
+  const realtime = experimental_useRealtime({
+    model: gateway.experimental_realtime('openai/gpt-realtime-2'),
+    api: {
+      token: '/api/realtime/setup',
+    },
+  });
+
+  // ...
+}
+```
+
+Do not expose your Gateway API key or OIDC token to browser clients. Only return
+the short-lived setup response from `getToken()`.
+
+<Note>
+  The Gateway WebSocket route transports the short-lived auth token via the
+  versioned `Sec-WebSocket-Protocol` subprotocol and the model id via the
+  `?ai-model-id=` query - the WebSocket transport of the `Authorization` and
+  `ai-model-id` headers the HTTP routes use. Subprotocol values must fit the
+  WebSocket token grammar, and the complete `Sec-WebSocket-Protocol` header
+  should stay compact (under an 8 KiB safe header budget).
+</Note>
+
+### Provider Options
+
+Gateway [provider options](#gateway-provider-options) — `tags`, `user`, `byok`, compliance flags, and so on — are set under `providerOptions.gateway` in the **session configuration**, mirroring how they ride the request body on the non-realtime routes. Include them in the session configuration you send to the Gateway, and the Gateway applies them server-side:
+
+```ts
+import type { GatewayProviderOptions } from '@ai-sdk/gateway';
+
+const gatewayOptions: GatewayProviderOptions = {
+  tags: ['cooking-coach', 'v2'],
+  user: 'user-123',
+};
+
+const sessionConfig = {
+  instructions: 'You are a concise voice assistant.',
+  providerOptions: { gateway: gatewayOptions },
+};
+```
+
+The `GatewayProviderOptions` type is exported from `@ai-sdk/gateway` for stable client-facing fields. The type also accepts service-owned option keys so the Gateway service can add or change server-side options without requiring an SDK release for every schema change. Runtime validation is owned by the Gateway service.
+
+<Note>
+  Provider options are sent in the initial session update after the socket
+  opens, so connect-time options such as `byok` and quota selection require a
+  Gateway that resolves them from that update. Routing knobs like `order` /
+  `only` do not apply to realtime, where the Gateway selects the
+  WebSocket-capable provider.
+</Note>
+
 ## Available Models
 
 The AI Gateway supports models from OpenAI, Anthropic, Google, Meta, xAI, Mistral, DeepSeek, Amazon Bedrock, Cohere, Perplexity, Alibaba, and other providers.
@@ -563,6 +655,93 @@ for await (const part of result.stream) {
 }
 ```
 
+#### Exa Search
+
+The Exa Search tool enables models to search the web using [Exa's Search API](https://exa.ai/docs/reference/search-api-guide-for-coding-agents). This tool is executed by the AI Gateway and returns token-efficient web excerpts for agent workflows.
+
+```ts
+import { gateway, generateText } from 'ai';
+
+const result = await generateText({
+  model: 'openai/gpt-5.4-nano',
+  prompt:
+    'Find the latest AI regulation updates and summarize the key changes.',
+  tools: {
+    exa_search: gateway.tools.exaSearch(),
+  },
+});
+
+console.log(result.text);
+console.log('Tool calls:', JSON.stringify(result.toolCalls, null, 2));
+console.log('Tool results:', JSON.stringify(result.toolResults, null, 2));
+```
+
+You can also configure the search with optional parameters:
+
+```ts
+import { gateway, generateText } from 'ai';
+
+const result = await generateText({
+  model: 'openai/gpt-5.4-nano',
+  prompt: 'Find recent AI regulation news from trusted sources.',
+  tools: {
+    exa_search: gateway.tools.exaSearch({
+      type: 'fast',
+      numResults: 5,
+      category: 'news',
+      includeDomains: ['reuters.com', 'bbc.com', 'nytimes.com'],
+      contents: {
+        highlights: true,
+        maxAgeHours: 24,
+      },
+    }),
+  },
+});
+
+console.log(result.text);
+console.log('Tool calls:', JSON.stringify(result.toolCalls, null, 2));
+console.log('Tool results:', JSON.stringify(result.toolResults, null, 2));
+```
+
+The Exa Search tool supports the following optional configuration options:
+
+- **type** _'auto' | 'fast' | 'instant'_
+
+  Search mode. `'auto'` is the default balance of speed and quality.
+
+- **numResults** _number_
+
+  Maximum number of results to return (1-100, default: 10).
+
+- **category** _'company' | 'people' | 'research paper' | 'news' | 'personal site' | 'financial report'_
+
+  Focus results on a specific content type.
+
+- **includeDomains** / **excludeDomains** _string[]_
+
+  Restrict or exclude search results by domain.
+
+- **startPublishedDate** / **endPublishedDate** _string_
+
+  Filter results by ISO 8601 publication date.
+
+- **contents** _object_
+
+  Control result extraction and freshness:
+  - `text` - Return full page text, optionally capped with `maxCharacters`
+  - `highlights` - Return token-efficient excerpts
+  - `maxAgeHours` - Control cached content freshness
+  - `livecrawlTimeout` - Livecrawl timeout in milliseconds
+  - `subpages` / `subpageTarget` - Crawl related subpages
+  - `extras.links` / `extras.imageLinks` - Extract links from pages
+
+The tool works with both `generateText` and `streamText`.
+
+This initial Gateway integration supports Exa's plain Search modes and
+token-efficient content controls. Deep synthesis modes and generated summaries
+are intentionally not exposed yet because they have separate pricing from
+standard Search.
+
 #### 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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-sdk/gateway",
   "private": false,
-  "version": "4.0.0-canary.98",
+  "version": "4.0.0",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -31,8 +31,8 @@
   },
   "dependencies": {
     "@vercel/oidc": "3.2.0",
-    "@ai-sdk/provider": "4.0.0-canary.17",
-    "@ai-sdk/provider-utils": "5.0.0-canary.45"
+    "@ai-sdk/provider": "4.0.0",
+    "@ai-sdk/provider-utils": "5.0.0"
   },
   "devDependencies": {
     "@types/node": "22.19.19",
@@ -40,7 +40,7 @@
     "tsx": "4.19.2",
     "typescript": "5.8.3",
     "zod": "3.25.76",
-    "@ai-sdk/test-server": "2.0.0-canary.6",
+    "@ai-sdk/test-server": "2.0.0",
     "@vercel/ai-tsconfig": "0.0.0"
   },
   "peerDependencies": {

package/src/errors/create-gateway-error.ts

@@ -8,6 +8,8 @@ import {
   modelNotFoundParamSchema,
 } from './gateway-model-not-found-error';
 import { GatewayInternalServerError } from './gateway-internal-server-error';
+import { GatewayFailedDependencyError } from './gateway-failed-dependency-error';
+import { GatewayForbiddenError } from './gateway-forbidden-error';
 import { GatewayResponseError } from './gateway-response-error';
 import {
   lazySchema,
@@ -101,6 +103,20 @@ export async function createGatewayErrorFromResponse({
         cause,
         generationId,
       });
+    case 'failed_dependency':
+      return new GatewayFailedDependencyError({
+        message,
+        statusCode,
+        cause,
+        generationId,
+      });
+    case 'forbidden':
+      return new GatewayForbiddenError({
+        message,
+        statusCode,
+        cause,
+        generationId,
+      });
     default:
       return new GatewayInternalServerError({
         message,

package/src/errors/gateway-failed-dependency-error.ts

@@ -0,0 +1,35 @@
+import { GatewayError } from './gateway-error';
+
+const name = 'GatewayFailedDependencyError';
+const marker = `vercel.ai.gateway.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * The request could not be fulfilled because a dependency it relied on was not
+ * available on the credentials or provider used to serve it (HTTP 424). Not
+ * retryable — the caller must change the request.
+ */
+export class GatewayFailedDependencyError extends GatewayError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly name = name;
+  readonly type = 'failed_dependency';
+
+  constructor({
+    message = 'Failed dependency',
+    statusCode = 424,
+    cause,
+    generationId,
+  }: {
+    message?: string;
+    statusCode?: number;
+    cause?: unknown;
+    generationId?: string;
+  } = {}) {
+    super({ message, statusCode, cause, generationId });
+  }
+
+  static isInstance(error: unknown): error is GatewayFailedDependencyError {
+    return GatewayError.hasMarker(error) && symbol in error;
+  }
+}

package/src/errors/gateway-forbidden-error.ts

@@ -0,0 +1,34 @@
+import { GatewayError } from './gateway-error';
+
+const name = 'GatewayForbiddenError';
+const marker = `vercel.ai.gateway.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Forbidden - the request was rejected by policy (e.g. a routing rule),
+ * not an authentication failure.
+ */
+export class GatewayForbiddenError extends GatewayError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly name = name;
+  readonly type = 'forbidden';
+
+  constructor({
+    message = 'Forbidden',
+    statusCode = 403,
+    cause,
+    generationId,
+  }: {
+    message?: string;
+    statusCode?: number;
+    cause?: unknown;
+    generationId?: string;
+  } = {}) {
+    super({ message, statusCode, cause, generationId });
+  }
+
+  static isInstance(error: unknown): error is GatewayForbiddenError {
+    return GatewayError.hasMarker(error) && symbol in error;
+  }
+}

package/src/errors/index.ts

@@ -6,6 +6,8 @@ export {
 export { extractApiCallResponse } from './extract-api-call-response';
 export { GatewayError } from './gateway-error';
 export { GatewayAuthenticationError } from './gateway-authentication-error';
+export { GatewayFailedDependencyError } from './gateway-failed-dependency-error';
+export { GatewayForbiddenError } from './gateway-forbidden-error';
 export { GatewayInternalServerError } from './gateway-internal-server-error';
 export { GatewayInvalidRequestError } from './gateway-invalid-request-error';
 export {

package/src/gateway-embedding-model.ts

@@ -98,7 +98,7 @@ export class GatewayEmbeddingModel implements EmbeddingModelV4 {
         providerMetadata:
           responseBody.providerMetadata as unknown as SharedV4ProviderMetadata,
         response: { headers: responseHeaders, body: rawValue },
-        warnings: [],
+        warnings: responseBody.warnings ?? [],
       };
     } catch (error) {
       throw await asGatewayError(
@@ -120,11 +120,34 @@ export class GatewayEmbeddingModel implements EmbeddingModelV4 {
   }
 }
 
+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('deprecated'),
+    setting: z.string(),
+    message: z.string(),
+  }),
+  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(),
       providerMetadata: z
         .record(z.string(), z.record(z.string(), z.unknown()))
         .optional(),

package/src/gateway-image-model.ts

@@ -167,6 +167,11 @@ const gatewayImageWarningSchema = z.discriminatedUnion('type', [
     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(),

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

@@ -53,8 +53,6 @@ export type GatewayModelId =
   | 'deepseek/deepseek-v3.2-thinking'
   | 'deepseek/deepseek-v4-flash'
   | 'deepseek/deepseek-v4-pro'
-  | 'google/gemini-2.0-flash'
-  | 'google/gemini-2.0-flash-lite'
   | 'google/gemini-2.5-flash'
   | 'google/gemini-2.5-flash-image'
   | 'google/gemini-2.5-flash-lite'
@@ -112,10 +110,10 @@ export type GatewayModelId =
   | 'mistral/pixtral-large'
   | 'moonshotai/kimi-k2'
   | 'moonshotai/kimi-k2-thinking'
-  | 'moonshotai/kimi-k2-thinking-turbo'
-  | 'moonshotai/kimi-k2-turbo'
   | 'moonshotai/kimi-k2.5'
   | 'moonshotai/kimi-k2.6'
+  | 'moonshotai/kimi-k2.7-code'
+  | 'moonshotai/kimi-k2.7-code-highspeed'
   | 'morph/morph-v3-fast'
   | 'morph/morph-v3-large'
   | 'nvidia/nemotron-3-nano-30b-a3b'
@@ -167,6 +165,7 @@ export type GatewayModelId =
   | 'perplexity/sonar'
   | 'perplexity/sonar-pro'
   | 'perplexity/sonar-reasoning-pro'
+  | 'sakana/fugu-ultra'
   | 'stepfun/step-3.5-flash'
   | 'stepfun/step-3.7-flash'
   | 'xai/grok-4.1-fast-non-reasoning'
@@ -195,5 +194,7 @@ export type GatewayModelId =
   | 'zai/glm-5'
   | 'zai/glm-5-turbo'
   | 'zai/glm-5.1'
+  | 'zai/glm-5.2'
+  | 'zai/glm-5.2-fast'
   | 'zai/glm-5v-turbo'
   | (string & {});

package/src/gateway-language-model.ts

@@ -1,7 +1,6 @@
 import type {
   LanguageModelV4,
   LanguageModelV4CallOptions,
-  LanguageModelV4FilePart,
   LanguageModelV4StreamPart,
   LanguageModelV4GenerateResult,
   LanguageModelV4StreamResult,
@@ -191,30 +190,27 @@ export class GatewayLanguageModel implements LanguageModelV4 {
     }
   }
 
-  private isFilePart(part: unknown) {
-    return (
-      part && typeof part === 'object' && 'type' in part && part.type === 'file'
-    );
-  }
-
   /**
-   * Encodes inline `Uint8Array` file part data to a base64 string in place.
+   * Encodes inline `Uint8Array` file data to a base64 string in place.
    * @param options - The options to encode.
-   * @returns The options with the file parts encoded.
+   * @returns The options with the file data encoded.
    */
   private maybeEncodeFileParts(options: LanguageModelV4CallOptions) {
     for (const message of options.prompt) {
+      if (!Array.isArray(message.content)) {
+        continue;
+      }
       for (const part of message.content) {
-        if (this.isFilePart(part)) {
-          const filePart = part as LanguageModelV4FilePart;
-          if (
-            filePart.data.type === 'data' &&
-            filePart.data.data instanceof Uint8Array
-          ) {
-            filePart.data = {
-              type: 'data',
-              data: Buffer.from(filePart.data.data).toString('base64'),
-            };
+        if (part.type === 'file' || part.type === 'reasoning-file') {
+          part.data = maybeBase64EncodeFileData(part.data);
+        } else if (
+          part.type === 'tool-result' &&
+          part.output.type === 'content'
+        ) {
+          for (const contentPart of part.output.value) {
+            if (contentPart.type === 'file') {
+              contentPart.data = maybeBase64EncodeFileData(contentPart.data);
+            }
           }
         }
       }
@@ -234,3 +230,13 @@ export class GatewayLanguageModel implements LanguageModelV4 {
     };
   }
 }
+
+function maybeBase64EncodeFileData<T extends { type: string }>(data: T): T {
+  if (data.type === 'data') {
+    const bytes = (data as { data?: unknown }).data;
+    if (bytes instanceof Uint8Array) {
+      return { ...data, data: Buffer.from(bytes).toString('base64') } as T;
+    }
+  }
+  return data;
+}

package/src/gateway-provider-options.ts

@@ -1,118 +1,52 @@
-import {
-  lazySchema,
-  zodSchema,
-  type InferSchema,
-} from '@ai-sdk/provider-utils';
-import { z } from 'zod/v4';
-
 // https://vercel.com/docs/ai-gateway/provider-options
-const gatewayProviderOptions = lazySchema(() =>
-  zodSchema(
-    z.object({
-      /**
-       * Array of provider slugs that are the only ones allowed to be used.
-       *
-       * Example: `['azure', 'openai']` will only allow Azure and OpenAI to be used.
-       */
-      only: z.array(z.string()).optional(),
-      /**
-       * Array of provider slugs that specifies the sequence in which providers should be attempted.
-       *
-       * Example: `['bedrock', 'anthropic']` will try Amazon Bedrock first, then Anthropic as fallback.
-       */
-      order: z.array(z.string()).optional(),
-      /**
-       * Sort providers by a performance or cost metric before routing.
-       *
-       * - `'cost'`: lowest cost first
-       * - `'ttft'`: lowest time-to-first-token first
-       * - `'tps'`: highest tokens-per-second first
-       */
-      sort: z.enum(['cost', 'ttft', 'tps']).optional(),
-      /**
-       * The unique identifier for the end user on behalf of whom the request was made.
-       *
-       * Used for spend tracking and attribution purposes.
-       */
-      user: z.string().optional(),
-      /**
-       * User-specified tags for use in reporting and filtering usage.
-       *
-       * For example, spend tracking reporting by feature or prompt version.
-       *
-       * 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(),
-      /**
-       * Request-scoped BYOK credentials to use instead of cached credentials.
-       *
-       * When provided, cached BYOK credentials are ignored entirely.
-       *
-       * Each provider can have multiple credentials (tried in order).
-       *
-       * Examples:
-       * - Simple: `{ 'anthropic': [{ apiKey: 'sk-ant-...' }] }`
-       * - Multiple: `{ 'vertex': [{ projectId: 'proj-1', privateKey: '...' }, { projectId: 'proj-2', privateKey: '...' }] }`
-       * - Multi-provider: `{ 'anthropic': [{ apiKey: '...' }], 'bedrock': [{ accessKeyId: '...', secretAccessKey: '...' }] }`
-       */
-      byok: z
-        .record(z.string(), z.array(z.record(z.string(), z.unknown())))
-        .optional(),
-      /**
-       * Whether to filter by only providers that have zero data retention
-       * agreements with Vercel for AI Gateway. When using BYOK credentials,
-       * this filter is not applied. If BYOK credentials fail and the request
-       * falls back to system credentials, only providers with zero data
-       * retention agreements will be used.
-       */
-      zeroDataRetention: z.boolean().optional(),
-      /**
-       * Whether to filter by only providers that do not train on prompt data.
-       * When using BYOK credentials, this filter is not applied. If BYOK
-       * credentials fail and the request falls back to system credentials,
-       * only providers that have agreements with Vercel for AI Gateway to not
-       * use prompts for model training will be used.
-       */
-      disallowPromptTraining: z.boolean().optional(),
-      /**
-       * Whether to filter by only providers that are HIPAA compliant with
-       * Vercel AI Gateway. When enabled, only providers that have agreements
-       * with Vercel AI Gateway for HIPAA compliance will be used.
-       */
-      hipaaCompliant: z.boolean().optional(),
-      /**
-       * The unique identifier for the entity against which quota is tracked.
-       *
-       * Used for quota management and enforcement purposes.
-       */
-      quotaEntityId: z.string().optional(),
-      /**
-       * 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: `{ byok: { openai: 5000, anthropic: 2000 } }`
-       */
-      providerTimeouts: z
-        .object({
-          byok: z.record(z.string(), z.number().int().min(1000)).optional(),
-        })
-        .optional(),
-      /**
-       * Unified service tier intent. Translated by the gateway into the
-       * per-provider option each provider expects, and overrides any tier
-       * also set in the per-provider options. Leave unset for provider
-       * default.
-       */
-      serviceTier: z.enum(['flex', 'priority']).optional(),
-    }),
-  ),
-);
+export type GatewayProviderOptions = {
+  /**
+   * Service-owned options may be added by the Gateway without requiring an SDK
+   * release. The Gateway service validates and applies the runtime schema.
+   */
+  [key: string]: unknown;
+
+  /** Request-scoped BYOK credentials to use instead of cached credentials. */
+  byok?: Record<string, Array<Record<string, unknown>>>;
+
+  /** Enables automatic caching behavior when supported by the Gateway. */
+  caching?: 'auto';
+
+  /** Filter to providers that do not train on prompt data. */
+  disallowPromptTraining?: boolean;
+
+  /** Filter to providers that are HIPAA compliant with Vercel AI Gateway. */
+  hipaaCompliant?: boolean;
+
+  /** Array of model slugs specifying fallback models to use in order. */
+  models?: string[];
+
+  /** Array of provider slugs that are the only ones allowed to be used. */
+  only?: string[];
+
+  /** Array of provider slugs specifying the provider attempt order. */
+  order?: string[];
+
+  /** Per-provider timeouts for BYOK credentials in milliseconds. */
+  providerTimeouts?: {
+    byok?: Record<string, number>;
+  };
+
+  /** Entity identifier against which quota is tracked. */
+  quotaEntityId?: string;
+
+  /** Unified service tier intent. */
+  serviceTier?: 'flex' | 'priority';
+
+  /** Sort providers by a performance or cost metric before routing. */
+  sort?: 'cost' | 'tps' | 'ttft';
+
+  /** User-specified tags for reporting and filtering usage. */
+  tags?: string[];
+
+  /** End-user identifier for spend tracking and attribution. */
+  user?: string;
 
-export type GatewayProviderOptions = InferSchema<typeof gatewayProviderOptions>;
+  /** Filter to providers with zero data retention agreements. */
+  zeroDataRetention?: boolean;
+};