@ai-sdk/gateway 4.0.0-beta.10 → 4.0.0-beta.109

package/src/gateway-model-entry.ts

@@ -1,4 +1,16 @@
-import type { LanguageModelV3 } from '@ai-sdk/provider';
+import type { LanguageModelV4 } from '@ai-sdk/provider';
+
+export const KNOWN_MODEL_TYPES = [
+  'embedding',
+  'image',
+  'language',
+  'reranking',
+  'speech',
+  'transcription',
+  'video',
+] as const;
+
+export type KnownModelType = (typeof KNOWN_MODEL_TYPES)[number];
 
 export interface GatewayLanguageModelEntry {
   /**
@@ -49,10 +61,10 @@ export interface GatewayLanguageModelEntry {
   /**
    * Optional field to differentiate between model types.
    */
-  modelType?: 'language' | 'embedding' | 'image' | 'video' | null;
+  modelType?: KnownModelType | null;
 }
 
 export type GatewayLanguageModelSpecification = Pick<
-  LanguageModelV3,
+  LanguageModelV4,
   'specificationVersion' | 'provider' | 'modelId'
 >;

package/src/gateway-provider-options.ts

@@ -1,80 +1,52 @@
-import { InferSchema, lazySchema, zodSchema } from '@ai-sdk/provider-utils';
-import { z } from 'zod/v4';
-
 // https://vercel.com/docs/ai-gateway/provider-options
-const gatewayLanguageModelOptions = 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(),
-      /**
-       * 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 state they have zero data
-       * retention with Vercel AI Gateway. When enabled, only providers that
-       * have agreements with Vercel AI Gateway for zero data retention will be
-       * used.
-       */
-      zeroDataRetention: z.boolean().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(),
-    }),
-  ),
-);
+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 GatewayLanguageModelOptions = InferSchema<
-  typeof gatewayLanguageModelOptions
->;
+  /** Filter to providers with zero data retention agreements. */
+  zeroDataRetention?: boolean;
+};

package/src/gateway-provider.ts

@@ -1,50 +1,78 @@
 import {
+  createJsonErrorResponseHandler,
+  createJsonResponseHandler,
   loadOptionalSetting,
+  postJsonToApi,
   withoutTrailingSlash,
+  withUserAgentSuffix,
   type FetchFunction,
 } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
 import { asGatewayError, GatewayAuthenticationError } from './errors';
 import {
   GATEWAY_AUTH_METHOD_HEADER,
-  parseAuthMethod,
-} from './errors/parse-auth-method';
+  VERCEL_AI_GATEWAY_TEAM_HEADER,
+} from './gateway-headers';
+import { parseAuthMethod } from './errors/parse-auth-method';
 import {
   GatewayFetchMetadata,
   type GatewayFetchMetadataResponse,
   type GatewayCreditsResponse,
 } from './gateway-fetch-metadata';
+import {
+  GatewaySpendReport,
+  type GatewaySpendReportParams,
+  type GatewaySpendReportResponse,
+} from './gateway-spend-report';
+import {
+  GatewayGenerationInfoFetcher,
+  type GatewayGenerationInfoParams,
+  type GatewayGenerationInfo,
+} from './gateway-generation-info';
 import { GatewayLanguageModel } from './gateway-language-model';
 import { GatewayEmbeddingModel } from './gateway-embedding-model';
 import { GatewayImageModel } from './gateway-image-model';
 import { GatewayVideoModel } from './gateway-video-model';
+import { GatewayRerankingModel } from './gateway-reranking-model';
+import { GatewaySpeechModel } from './gateway-speech-model';
+import { GatewayTranscriptionModel } from './gateway-transcription-model';
+import { GatewayRealtimeModel } from './gateway-realtime-model';
 import type { GatewayEmbeddingModelId } from './gateway-embedding-model-settings';
 import type { GatewayImageModelId } from './gateway-image-model-settings';
+import type { GatewayRerankingModelId } from './gateway-reranking-model-settings';
+import type { GatewaySpeechModelId } from './gateway-speech-model-settings';
+import type { GatewayTranscriptionModelId } from './gateway-transcription-model-settings';
+import type { GatewayRealtimeModelId } from './gateway-realtime-model-settings';
 import type { GatewayVideoModelId } from './gateway-video-model-settings';
 import { gatewayTools } from './gateway-tools';
 import { getVercelOidcToken, getVercelRequestId } from './vercel-environment';
 import type { GatewayModelId } from './gateway-language-model-settings';
 import type {
-  LanguageModelV3,
-  EmbeddingModelV3,
-  ImageModelV3,
-  Experimental_VideoModelV3,
-  ProviderV3,
+  LanguageModelV4,
+  EmbeddingModelV4,
+  ImageModelV4,
+  RerankingModelV4,
+  SpeechModelV4,
+  TranscriptionModelV4,
+  Experimental_VideoModelV4,
+  Experimental_RealtimeFactoryV4 as RealtimeFactoryV4,
+  Experimental_RealtimeFactoryV4GetTokenOptions as RealtimeFactoryV4GetTokenOptions,
+  ProviderV4,
 } from '@ai-sdk/provider';
-import { withUserAgentSuffix } from '@ai-sdk/provider-utils';
 import { VERSION } from './version';
 
-export interface GatewayProvider extends ProviderV3 {
-  (modelId: GatewayModelId): LanguageModelV3;
+export interface GatewayProvider extends ProviderV4 {
+  (modelId: GatewayModelId): LanguageModelV4;
 
   /**
    * Creates a model for text generation.
    */
-  chat(modelId: GatewayModelId): LanguageModelV3;
+  chat(modelId: GatewayModelId): LanguageModelV4;
 
   /**
    * Creates a model for text generation.
    */
-  languageModel(modelId: GatewayModelId): LanguageModelV3;
+  languageModel(modelId: GatewayModelId): LanguageModelV4;
 
   /**
    * Returns available providers and models for use with the remote provider.
@@ -56,40 +84,94 @@ export interface GatewayProvider extends ProviderV3 {
    */
   getCredits(): Promise<GatewayCreditsResponse>;
 
+  /**
+   * Returns a spend report with cost, token, and request count data,
+   * aggregated by the specified dimension.
+   */
+  getSpendReport(
+    params: GatewaySpendReportParams,
+  ): Promise<GatewaySpendReportResponse>;
+
+  /**
+   * Returns detailed information about a specific generation by its ID,
+   * including cost, token usage, latency, and provider details.
+   */
+  getGenerationInfo(
+    params: GatewayGenerationInfoParams,
+  ): Promise<GatewayGenerationInfo>;
+
   /**
    * Creates a model for generating text embeddings.
    */
-  embedding(modelId: GatewayEmbeddingModelId): EmbeddingModelV3;
+  embedding(modelId: GatewayEmbeddingModelId): EmbeddingModelV4;
 
   /**
    * Creates a model for generating text embeddings.
    */
-  embeddingModel(modelId: GatewayEmbeddingModelId): EmbeddingModelV3;
+  embeddingModel(modelId: GatewayEmbeddingModelId): EmbeddingModelV4;
 
   /**
    * @deprecated Use `embeddingModel` instead.
    */
-  textEmbeddingModel(modelId: GatewayEmbeddingModelId): EmbeddingModelV3;
+  textEmbeddingModel(modelId: GatewayEmbeddingModelId): EmbeddingModelV4;
 
   /**
    * Creates a model for generating images.
    */
-  image(modelId: GatewayImageModelId): ImageModelV3;
+  image(modelId: GatewayImageModelId): ImageModelV4;
 
   /**
    * Creates a model for generating images.
    */
-  imageModel(modelId: GatewayImageModelId): ImageModelV3;
+  imageModel(modelId: GatewayImageModelId): ImageModelV4;
 
   /**
    * Creates a model for generating videos.
    */
-  video(modelId: GatewayVideoModelId): Experimental_VideoModelV3;
+  video(modelId: GatewayVideoModelId): Experimental_VideoModelV4;
 
   /**
    * Creates a model for generating videos.
    */
-  videoModel(modelId: GatewayVideoModelId): Experimental_VideoModelV3;
+  videoModel(modelId: GatewayVideoModelId): Experimental_VideoModelV4;
+
+  /**
+   * Creates a model for reranking documents.
+   */
+  reranking(modelId: GatewayRerankingModelId): RerankingModelV4;
+
+  /**
+   * Creates a model for reranking documents.
+   */
+  rerankingModel(modelId: GatewayRerankingModelId): RerankingModelV4;
+
+  /**
+   * Creates a model for text-to-speech generation.
+   */
+  speech(modelId: GatewaySpeechModelId): SpeechModelV4;
+
+  /**
+   * Creates a model for text-to-speech generation.
+   */
+  speechModel(modelId: GatewaySpeechModelId): SpeechModelV4;
+
+  /**
+   * Creates a model for audio transcription.
+   */
+  transcription(modelId: GatewayTranscriptionModelId): TranscriptionModelV4;
+
+  /**
+   * Creates a model for audio transcription.
+   */
+  transcriptionModel(
+    modelId: GatewayTranscriptionModelId,
+  ): TranscriptionModelV4;
+
+  /**
+   * Creates an experimental realtime model for bidirectional audio/text
+   * communication over WebSocket, normalized through the AI Gateway.
+   */
+  experimental_realtime: RealtimeFactoryV4;
 
   /**
    * Gateway-specific tools executed server-side.
@@ -99,15 +181,22 @@ export interface GatewayProvider extends ProviderV3 {
 
 export interface GatewayProviderSettings {
   /**
-   * The base URL prefix for API calls. Defaults to `https://ai-gateway.vercel.sh/v1/ai`.
+   * The base URL prefix for API calls. Defaults to `https://ai-gateway.vercel.sh/v4/ai`.
    */
   baseURL?: string;
 
   /**
-   * API key that is being sent using the `Authorization` header.
+   * API key or Vercel access token that is being sent using the `Authorization`
+   * header. It defaults to the `AI_GATEWAY_API_KEY` environment variable.
    */
   apiKey?: string;
 
+  /**
+   * Vercel team ID or slug to scope requests for access tokens that can access
+   * multiple teams.
+   */
+  teamIdOrSlug?: string;
+
   /**
    * Custom headers to include in the requests.
    */
@@ -134,10 +223,16 @@ export interface GatewayProviderSettings {
 
 const AI_GATEWAY_PROTOCOL_VERSION = '0.0.1';
 
+/** Response shape of `POST /v1/realtime/client-secrets`. `expiresAt` is epoch seconds. */
+const gatewayClientSecretResponseSchema = z.object({
+  token: z.string(),
+  expiresAt: z.number().nullish(),
+});
+
 /**
  * Create a remote provider instance.
  */
-export function createGatewayProvider(
+export function createGateway(
   options: GatewayProviderSettings = {},
 ): GatewayProvider {
   let pendingMetadata: Promise<GatewayFetchMetadataResponse> | null = null;
@@ -148,20 +243,28 @@ export function createGatewayProvider(
 
   const baseURL =
     withoutTrailingSlash(options.baseURL) ??
-    'https://ai-gateway.vercel.sh/v3/ai';
+    'https://ai-gateway.vercel.sh/v4/ai';
+
+  const createAuthHeaders = (auth: {
+    token: string;
+    authMethod: 'api-key' | 'oidc';
+  }) =>
+    withUserAgentSuffix(
+      {
+        Authorization: `Bearer ${auth.token}`,
+        'ai-gateway-protocol-version': AI_GATEWAY_PROTOCOL_VERSION,
+        [GATEWAY_AUTH_METHOD_HEADER]: auth.authMethod,
+        ...(options.teamIdOrSlug != null
+          ? { [VERCEL_AI_GATEWAY_TEAM_HEADER]: options.teamIdOrSlug }
+          : {}),
+        ...options.headers,
+      },
+      `ai-sdk/gateway/${VERSION}`,
+    );
 
   const getHeaders = async () => {
     try {
-      const auth = await getGatewayAuthToken(options);
-      return withUserAgentSuffix(
-        {
-          Authorization: `Bearer ${auth.token}`,
-          'ai-gateway-protocol-version': AI_GATEWAY_PROTOCOL_VERSION,
-          [GATEWAY_AUTH_METHOD_HEADER]: auth.authMethod,
-          ...options.headers,
-        },
-        `ai-sdk/gateway/${VERSION}`,
-      );
+      return createAuthHeaders(await getGatewayAuthToken(options));
     } catch (error) {
       throw GatewayAuthenticationError.createContextualError({
         apiKeyProvided: false,
@@ -172,6 +275,62 @@ export function createGatewayProvider(
     }
   };
 
+  const getRealtimeAuthToken = async () => {
+    try {
+      return await getGatewayAuthToken(options);
+    } catch (error) {
+      throw GatewayAuthenticationError.createContextualError({
+        apiKeyProvided: false,
+        oidcTokenProvided: false,
+        statusCode: 401,
+        cause: error,
+      });
+    }
+  };
+
+  // Mints a short-lived realtime client secret (`vcst_`) via the Gateway's
+  // `/v1/realtime/client-secrets` route, authenticated with the long-lived
+  // Gateway credential. Server-side only (asserted) — the credential never
+  // belongs in a browser; the browser receives only the minted token. The
+  // mint route lives at the gateway origin's `/v1/realtime/client-secrets`,
+  // not under the realtime `baseURL` path (which targets `/v4/ai`), so the
+  // URL is resolved against the origin.
+  const mintRealtimeClientSecret = async (params: {
+    modelId: string;
+    expiresAfterSeconds?: number;
+  }): Promise<{ token: string; expiresAt?: number }> => {
+    assertGatewayRealtimeServerEnvironment();
+    const auth = await getRealtimeAuthToken();
+    const headers = createAuthHeaders(auth);
+    const url = new URL('/v1/realtime/client-secrets', baseURL).toString();
+    try {
+      const { value } = await postJsonToApi({
+        url,
+        headers,
+        body: {
+          model: params.modelId,
+          ...(params.expiresAfterSeconds != null && {
+            expiresIn: params.expiresAfterSeconds,
+          }),
+        },
+        successfulResponseHandler: createJsonResponseHandler(
+          gatewayClientSecretResponseSchema,
+        ),
+        failedResponseHandler: createJsonErrorResponseHandler({
+          errorSchema: z.any(),
+          errorToMessage: data => data,
+        }),
+        fetch: options.fetch,
+      });
+      return {
+        token: value.token,
+        ...(value.expiresAt != null && { expiresAt: value.expiresAt }),
+      };
+    } catch (error) {
+      throw await asGatewayError(error, await parseAuthMethod(headers));
+    }
+  };
+
   const createO11yHeaders = () => {
     const deploymentId = loadOptionalSetting({
       settingValue: undefined,
@@ -253,6 +412,36 @@ export function createGatewayProvider(
       });
   };
 
+  const getSpendReport = async (params: GatewaySpendReportParams) => {
+    return new GatewaySpendReport({
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    })
+      .getSpendReport(params)
+      .catch(async (error: unknown) => {
+        throw await asGatewayError(
+          error,
+          await parseAuthMethod(await getHeaders()),
+        );
+      });
+  };
+
+  const getGenerationInfo = async (params: GatewayGenerationInfoParams) => {
+    return new GatewayGenerationInfoFetcher({
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    })
+      .getGenerationInfo(params)
+      .catch(async (error: unknown) => {
+        throw await asGatewayError(
+          error,
+          await parseAuthMethod(await getHeaders()),
+        );
+      });
+  };
+
   const provider = function (modelId: GatewayModelId) {
     if (new.target) {
       throw new Error(
@@ -263,9 +452,11 @@ export function createGatewayProvider(
     return createLanguageModel(modelId);
   };
 
-  provider.specificationVersion = 'v3' as const;
+  provider.specificationVersion = 'v4' as const;
   provider.getAvailableModels = getAvailableModels;
   provider.getCredits = getCredits;
+  provider.getSpendReport = getSpendReport;
+  provider.getGenerationInfo = getGenerationInfo;
   provider.imageModel = (modelId: GatewayImageModelId) => {
     return new GatewayImageModel(modelId, {
       provider: 'gateway',
@@ -296,6 +487,68 @@ export function createGatewayProvider(
       o11yHeaders: createO11yHeaders(),
     });
   };
+  const createRerankingModel = (modelId: GatewayRerankingModelId) => {
+    return new GatewayRerankingModel(modelId, {
+      provider: 'gateway',
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+      o11yHeaders: createO11yHeaders(),
+    });
+  };
+  provider.rerankingModel = createRerankingModel;
+  provider.reranking = createRerankingModel;
+  const createSpeechModel = (modelId: GatewaySpeechModelId) => {
+    return new GatewaySpeechModel(modelId, {
+      provider: 'gateway',
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+      o11yHeaders: createO11yHeaders(),
+    });
+  };
+  provider.speechModel = createSpeechModel;
+  provider.speech = createSpeechModel;
+  const createTranscriptionModel = (modelId: GatewayTranscriptionModelId) => {
+    return new GatewayTranscriptionModel(modelId, {
+      provider: 'gateway',
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+      o11yHeaders: createO11yHeaders(),
+    });
+  };
+  provider.transcriptionModel = createTranscriptionModel;
+  provider.transcription = createTranscriptionModel;
+
+  // No server-environment guard here: building the realtime model is just the
+  // event codec + WebSocket-config helper, which the browser legitimately
+  // needs to drive the transport with a server-minted client secret. The
+  // server-only boundary is enforced on minting itself
+  // (`mintRealtimeClientSecret`), which requires the Gateway credential.
+  const createRealtimeModel = (modelId: GatewayRealtimeModelId) =>
+    new GatewayRealtimeModel(modelId, {
+      provider: 'gateway.realtime',
+      baseURL,
+      teamIdOrSlug: options.teamIdOrSlug,
+      createClientSecret: mintRealtimeClientSecret,
+    });
+  provider.experimental_realtime = Object.assign(
+    (modelId: GatewayRealtimeModelId) => createRealtimeModel(modelId),
+    {
+      getToken: async (tokenOptions: RealtimeFactoryV4GetTokenOptions) => {
+        const { model: modelId, ...secretOptions } = tokenOptions;
+        const model = createRealtimeModel(modelId);
+        const secret = await model.doCreateClientSecret(secretOptions);
+        return {
+          token: secret.token,
+          url: secret.url,
+          ...(secret.expiresAt != null && { expiresAt: secret.expiresAt }),
+        };
+      },
+    },
+  ) as RealtimeFactoryV4;
+
   provider.chat = provider.languageModel;
   provider.embedding = provider.embeddingModel;
   provider.image = provider.imageModel;
@@ -304,7 +557,7 @@ export function createGatewayProvider(
   return provider;
 }
 
-export const gateway = createGatewayProvider();
+export const gateway = createGateway();
 
 export async function getGatewayAuthToken(
   options: GatewayProviderSettings,
@@ -327,3 +580,11 @@ export async function getGatewayAuthToken(
     authMethod: 'oidc',
   };
 }
+
+function assertGatewayRealtimeServerEnvironment(): void {
+  if (typeof globalThis.window !== 'undefined') {
+    throw new Error(
+      'AI Gateway realtime client secrets must be minted server-side: minting needs your Gateway credential, which must never reach the browser. Call gateway.experimental_realtime.getToken() from your server and pass the returned token to the client.',
+    );
+  }
+}