@ai-sdk/gateway 4.0.75 → 4.0.77

package/docs/00-ai-gateway.mdx

@@ -213,21 +213,25 @@ started, AI SDK Core exposes it as a
 Use its `type`, `code`, `statusCode`, and `isRetryable` metadata to classify
 the failure without inspecting the Gateway's serialized error payload.
 
-## Text Batches
+## Batch
 
 <Note type="warning">
-  Text batch support is experimental and the API may change in patch releases.
+  Batch support is experimental and the API may change in patch releases.
 </Note>
 
-AI Gateway supports durable text batches through `experimental_startTextBatch`, `experimental_getBatchStatus`, and `experimental_getBatchResults`. See the [AI Gateway batch processing guide](https://vercel.com/docs/ai-gateway/models-and-providers/batch-processing) for supported models, limits, and the complete lifecycle.
+AI Gateway supports durable text batches through `experimental_startBatch`,
+`experimental_getBatchStatus`, and `experimental_getBatchResults`. See
+[Batch](/docs/ai-sdk-core/batch) for the provider-agnostic workflow,
+and the [AI Gateway batch processing guide](https://vercel.com/docs/ai-gateway/models-and-providers/batch-processing)
+for supported models, limits, and Gateway-specific behavior.
 
 Pass a publicly reachable HTTPS `webhookUrl` when starting a batch to receive a terminal notification instead of polling. AI Gateway sends `batch.completed`, `batch.failed`, or `batch.cancelled`. The event contains terminal status information but not batch results. Completion webhooks are an AI Gateway capability; direct Anthropic and OpenAI batch providers return an unsupported warning when this option is provided.
 
 ```ts filename="start-batch.ts"
 import { randomUUID } from 'node:crypto';
 import {
-  experimental_startTextBatch as startTextBatch,
-  type Experimental_TextBatchReference as TextBatchReference,
+  experimental_startBatch as startBatch,
+  type Experimental_BatchReference as BatchReference,
   type GatewayProviderMetadata,
 } from 'ai';
 
@@ -240,11 +244,20 @@ const model = 'anthropic/claude-haiku-4.5' as const;
 // pending record rather than an unknown callback.
 await reserveBatchWebhook(token);
 
-const batch = await startTextBatch({
-  model,
+const batch = await startBatch({
   requests: [
-    { id: 'france', prompt: 'What is the capital of France?' },
-    { id: 'germany', prompt: 'What is the capital of Germany?' },
+    {
+      id: 'france',
+      type: 'text',
+      model,
+      prompt: 'What is the capital of France?',
+    },
+    {
+      id: 'germany',
+      type: 'text',
+      model,
+      prompt: 'What is the capital of Germany?',
+    },
   ],
   providerOptions: {
     gateway: { idempotencyKey: token },
@@ -264,20 +277,17 @@ if (typeof signingSecret !== 'string') {
 // Keep sensitive provider metadata out of the receiver queue and logs.
 const batchReference = {
   version: batch.version,
-  type: batch.type,
   id: batch.id,
   provider: batch.provider,
-  modelId: batch.modelId,
-} satisfies TextBatchReference;
+} satisfies BatchReference;
 
 await completeBatchWebhookReservation(token, {
   batch: batchReference,
-  model,
   signingSecret,
 });
 ```
 
-The signing secret is returned only in the start response. Reserve the callback token before submitting the batch, then persist the secret, model, and minimal `batch` reference before the process exits. The stable `providerOptions.gateway.idempotencyKey` makes retrying an ambiguous start safe. Reuse the reserved token when retrying; do not generate a new one. Delete the reservation after a definitive start failure. While the reservation is still pending, the receiver should return a retryable response so an early delivery is sent again after setup completes.
+The signing secret is returned only in the start response. Reserve the callback token before submitting the batch, then persist the secret and minimal `batch` reference before the process exits. The stable `providerOptions.gateway.idempotencyKey` makes retrying an ambiguous start safe. Reuse the reserved token when retrying; do not generate a new one. Delete the reservation after a definitive start failure. While the reservation is still pending, the receiver should return a retryable response so an early delivery is sent again after setup completes.
 
 The receiver must verify the `x-ai-gateway-signature` header against a bounded raw request body before trusting the event:
 
@@ -340,7 +350,6 @@ export async function POST(request: Request) {
   await enqueueBatchResultFetch({
     batch: record.batch,
     deliveryId,
-    model: record.model,
   });
 
   return new Response(null, { status: 204 });
@@ -399,7 +408,11 @@ function verifySignature({
 
 The signature header has the form `t=<unix seconds>,v1=<hex digest>`, where `v1` is the HMAC-SHA256 digest of `"<t>.<raw body>"`. Verify a size-limited raw request body rather than a re-serialized object, use a timing-safe comparison, reject stale timestamps, and reject events whose `data.jobId` does not match the persisted `batch.id`.
 
-AI Gateway expects a 2xx response within 10 seconds and retries failed deliveries. It does not follow redirects, so the callback endpoint itself must return the 2xx response. Retries carry the same `x-ai-gateway-idempotency-key` value (`<jobId>-<status>`), which receivers can use for deduplication. After verification, pass the persisted model and `batch` reference to `experimental_getBatchStatus` and `experimental_getBatchResults`. Delivery is best-effort, so periodically reconcile persisted batches by status as a fallback for a notification that exhausts its retries.
+AI Gateway expects a 2xx response within 10 seconds and retries failed deliveries. It does not follow redirects, so the callback endpoint itself must return the 2xx response. Retries carry the same `x-ai-gateway-idempotency-key` value (`<jobId>-<status>`), which receivers can use for deduplication. After verification, pass the persisted `batch` reference to `experimental_getBatchStatus` and `experimental_getBatchResults`. Delivery is best-effort, so periodically reconcile persisted batches by status as a fallback for a notification that exhausts its retries.
+
+Each request specifies its `type` and `model`. AI Gateway currently requires
+every text request in a batch to use the same model and throws before submission
+when the models differ.
 
 ## Reranking Models
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-sdk/gateway",
   "private": false,
-  "version": "4.0.75",
+  "version": "4.0.77",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -30,8 +30,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "4.0.10",
-    "@ai-sdk/provider-utils": "5.0.36",
+    "@ai-sdk/provider": "4.0.12",
+    "@ai-sdk/provider-utils": "5.0.38",
     "@vercel/oidc": "3.2.0"
   },
   "devDependencies": {

package/src/{gateway-language-model-batch.ts → gateway-batch.ts}

@@ -1,12 +1,12 @@
 import {
-  type Experimental_BatchLanguageModelV4 as BatchLanguageModelV4,
+  InvalidArgumentError,
+  type Experimental_BatchV4 as BatchV4,
   type Experimental_BatchV4ItemResult as BatchV4ItemResult,
   type Experimental_BatchV4OperationOptions as BatchV4OperationOptions,
-  type Experimental_BatchV4StartOptions as BatchV4StartOptions,
   type Experimental_BatchV4StartResult as BatchV4StartResult,
   type Experimental_BatchV4Status as BatchV4Status,
-  type Experimental_LanguageModelV4BatchRequest as LanguageModelV4BatchRequest,
-  type LanguageModelV4GenerateResult,
+  type Experimental_BatchV4StartOptions as BatchV4StartOptions,
+  type LanguageModelV4CallOptions,
   type SharedV4ProviderMetadata,
   type SharedV4ProviderOptions,
 } from '@ai-sdk/provider';
@@ -20,35 +20,20 @@ import {
   normalizeBatchRequestCounts,
   postJsonToApi,
   resolve,
-  WORKFLOW_SERIALIZE,
-  WORKFLOW_DESERIALIZE,
 } from '@ai-sdk/provider-utils';
 import { z } from './zod';
-import {
-  GatewayLanguageModel,
-  type GatewayChatConfig,
-} from './gateway-language-model';
+import type { GatewayChatConfig } from './gateway-language-model';
 import type { GatewayModelId } from './gateway-language-model-settings';
 import { asGatewayError } from './errors';
 import { parseAuthMethod } from './errors/parse-auth-method';
 
-export class GatewayBatchLanguageModel
-  extends GatewayLanguageModel
-  implements BatchLanguageModelV4
-{
-  static [WORKFLOW_SERIALIZE](model: GatewayBatchLanguageModel) {
-    return GatewayLanguageModel[WORKFLOW_SERIALIZE](model);
-  }
-
-  static [WORKFLOW_DESERIALIZE](options: {
-    modelId: GatewayModelId;
-    config: GatewayChatConfig;
-  }) {
-    return new GatewayBatchLanguageModel(options.modelId, options.config);
-  }
+export class GatewayBatch implements BatchV4<{ text: GatewayModelId }> {
+  readonly specificationVersion = 'v4' as const;
+  readonly provider: string;
+  readonly supportedUrls = { '*/*': [/.*/] };
 
-  constructor(modelId: GatewayModelId, config: GatewayChatConfig) {
-    super(modelId, config);
+  constructor(private readonly config: GatewayChatConfig) {
+    this.provider = `${config.provider}.batch`;
   }
 
   /**
@@ -58,13 +43,17 @@ export class GatewayBatchLanguageModel
    * server-side, so status and results always route back through the
    * Gateway job.
    */
-  async experimental_doStartBatch({
+  async doStartBatch({
     requests,
     providerOptions,
     headers,
     abortSignal,
     webhookUrl,
-  }: BatchV4StartOptions<LanguageModelV4BatchRequest>): Promise<BatchV4StartResult> {
+  }: BatchV4StartOptions<{
+    text: GatewayModelId;
+  }>): Promise<BatchV4StartResult> {
+    const modelId = validateSingleModel(requests);
+
     const resolvedHeaders = this.config.headers
       ? await resolve(this.config.headers)
       : undefined;
@@ -78,7 +67,7 @@ export class GatewayBatchLanguageModel
         headers: combineHeaders(
           resolvedHeaders,
           headers,
-          this.getBatchConfigHeaders(),
+          { 'ai-model-id': modelId },
           await resolve(this.config.o11yHeaders),
           idempotencyKey != null
             ? { 'idempotency-key': idempotencyKey }
@@ -86,10 +75,11 @@ export class GatewayBatchLanguageModel
         ),
         body: {
           ...(webhookUrl != null && { callbackUrl: webhookUrl }),
-          modelId: this.modelId,
           requests: requests.map(request => ({
             id: request.id,
-            options: this.maybeEncodeFileParts(request.options),
+            type: request.type,
+            modelId: request.modelId,
+            options: maybeEncodeBatchFileParts(request.options),
           })),
           ...(forwardedProviderOptions != null && {
             providerOptions: forwardedProviderOptions,
@@ -129,7 +119,7 @@ export class GatewayBatchLanguageModel
    * Retrieves the lifecycle status of a Gateway batch job
    * (`POST {baseURL}/batch/status`).
    */
-  async experimental_doGetBatchStatus({
+  async doGetBatchStatus({
     batchId,
     headers,
     abortSignal,
@@ -144,7 +134,6 @@ export class GatewayBatchLanguageModel
         headers: combineHeaders(
           resolvedHeaders,
           headers,
-          this.getBatchConfigHeaders(),
           await resolve(this.config.o11yHeaders),
         ),
         body: { batchId },
@@ -178,13 +167,11 @@ export class GatewayBatchLanguageModel
    * (id + status) and passed through — the Gateway sanitizes them
    * server-side. The route responds 400 while the batch is non-terminal.
    */
-  async experimental_doGetBatchResults({
+  async doGetBatchResults({
     batchId,
     headers,
     abortSignal,
-  }: BatchV4OperationOptions): Promise<
-    ReadableStream<BatchV4ItemResult<LanguageModelV4GenerateResult>>
-  > {
+  }: BatchV4OperationOptions): Promise<ReadableStream<BatchV4ItemResult>> {
     const resolvedHeaders = this.config.headers
       ? await resolve(this.config.headers)
       : undefined;
@@ -195,7 +182,6 @@ export class GatewayBatchLanguageModel
         headers: combineHeaders(
           resolvedHeaders,
           headers,
-          this.getBatchConfigHeaders(),
           await resolve(this.config.o11yHeaders),
         ),
         body: { batchId },
@@ -227,12 +213,67 @@ export class GatewayBatchLanguageModel
   private getBatchUrl(path: 'results' | 'start' | 'status') {
     return `${this.config.baseURL}/batch/${path}`;
   }
+}
+
+function maybeEncodeBatchFileParts<
+  T extends Pick<LanguageModelV4CallOptions, 'prompt'>,
+>(options: T): T {
+  for (const message of options.prompt) {
+    if (!Array.isArray(message.content)) {
+      continue;
+    }
+    for (const part of message.content) {
+      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);
+          }
+        }
+      }
+    }
+  }
+  return options;
+}
+
+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;
+}
+
+function validateSingleModel(
+  requests: BatchV4StartOptions<{ text: GatewayModelId }>['requests'],
+): GatewayModelId {
+  const modelId = requests[0]?.modelId;
+
+  if (modelId == null) {
+    throw new InvalidArgumentError({
+      argument: 'requests',
+      message: 'The AI Gateway Batch API requires at least one request.',
+    });
+  }
 
-  private getBatchConfigHeaders() {
-    return {
-      'ai-model-id': this.modelId,
-    };
+  for (const request of requests) {
+    if (request.modelId !== modelId) {
+      throw new InvalidArgumentError({
+        argument: 'requests',
+        message:
+          'The AI Gateway Batch API requires all requests in a batch to use ' +
+          `the same model. Found "${modelId}" and "${request.modelId}".`,
+      });
+    }
   }
+
+  return modelId;
 }
 
 /**
@@ -360,9 +401,9 @@ function convertGatewayBatchStatus(body: {
  */
 async function* convertGatewayBatchResultLines(
   lines: AsyncIterable<unknown>,
-): AsyncGenerator<BatchV4ItemResult<LanguageModelV4GenerateResult>> {
+): AsyncGenerator<BatchV4ItemResult> {
   for await (const line of lines) {
-    const item = line as BatchV4ItemResult<LanguageModelV4GenerateResult>;
+    const item = line as BatchV4ItemResult;
 
     // JSON carries `response.timestamp` as an ISO string; core expects a Date.
     if (item.status === 'succeeded') {
@@ -378,6 +419,7 @@ async function* convertGatewayBatchResultLines(
 
 const gatewayBatchItemResultLineSchema = z
   .object({
+    type: z.literal('text'),
     id: z.string(),
     status: z.enum(['cancelled', 'expired', 'failed', 'succeeded']),
   })

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

@@ -18,6 +18,8 @@ export type GatewayImageModelId =
   | 'openai/gpt-image-1-mini'
   | 'openai/gpt-image-1.5'
   | 'openai/gpt-image-2'
+  | 'openai/gpt-image-2.5-flare'
+  | 'openai/gpt-image-2.5-sunburst'
   | 'prodia/flux-fast-schnell'
   | 'quiverai/arrow-1.1'
   | 'recraft/recraft-v2'

package/src/gateway-image-model.ts

@@ -105,6 +105,9 @@ export class GatewayImageModel implements ImageModelV4 {
 
       return {
         images: responseBody.images, // Always base64 strings from server
+        ...(responseBody.isRetryable != null && {
+          isRetryable: responseBody.isRetryable,
+        }),
         warnings: responseBody.warnings ?? [],
         providerMetadata:
           responseBody.providerMetadata as ImageModelV4ProviderMetadata,
@@ -187,6 +190,7 @@ const gatewayImageUsageSchema = z.object({
 
 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)

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

@@ -64,6 +64,7 @@ export type GatewayModelId =
   | 'deepseek/deepseek-v4-flash-vision-exp'
   | 'deepseek/deepseek-v4-pro'
   | 'deepseek/deepseek-v4-pro-0813'
+  | 'deepseek/deepseek-v4.1-flash-beta'
   | 'google/gemini-2.5-flash'
   | 'google/gemini-2.5-flash-image'
   | 'google/gemini-2.5-flash-lite'
@@ -84,10 +85,13 @@ export type GatewayModelId =
   | 'google/gemma-4-26b-a4b-it'
   | 'google/gemma-4-31b-it'
   | 'inception/mercury-2'
+  | 'inception/mercury-2.5'
   | 'inception/mercury-coder-small'
   | 'inclusionai/ling-3.0-flash'
   | 'inclusionai/ling-3.0-flash-fin'
   | 'inclusionai/ling-3.0-flash-fin-free'
+  | 'inclusionai/ling-3.0-flash-sante'
+  | 'inclusionai/ling-3.0-flash-sante-free'
   | 'interfaze/interfaze-beta'
   | 'kwaipilot/kat-coder-air-v2.5'
   | 'kwaipilot/kat-coder-pro-v1'
@@ -110,10 +114,8 @@ export type GatewayModelId =
   | 'minimax/minimax-m2.5'
   | 'minimax/minimax-m2.5-highspeed'
   | 'minimax/minimax-m2.7'
-  | 'minimax/minimax-m2.7-free'
   | 'minimax/minimax-m2.7-highspeed'
   | 'minimax/minimax-m3'
-  | 'minimax/minimax-m3-free'
   | 'mistral/codestral'
   | 'mistral/devstral-2'
   | 'mistral/devstral-small-2'
@@ -188,6 +190,7 @@ export type GatewayModelId =
   | 'openai/gpt-5.6-terra'
   | 'openai/gpt-5.6-terra-fast'
   | 'openai/gpt-6-astra'
+  | 'openai/gpt-6-astra-fast'
   | 'openai/gpt-oss-120b'
   | 'openai/gpt-oss-20b'
   | 'openai/gpt-oss-safeguard-120b'
@@ -229,7 +232,6 @@ export type GatewayModelId =
   | 'thinkingmachines/inkling-small'
   | 'xiaomi/mimo-v2.5'
   | 'xiaomi/mimo-v2.5-pro'
-  | 'xiaomi/mimo-v2.5-pro-ultraspeed'
   | 'zai/glm-4.5'
   | 'zai/glm-4.5-air'
   | 'zai/glm-4.5v'
@@ -245,6 +247,5 @@ export type GatewayModelId =
   | 'zai/glm-5.3'
   | 'zai/glm-5.3-fast'
   | 'zai/glm-5.3-flash'
-  | 'zai/glm-5.3-promo-50'
   | 'zai/glm-5v-turbo'
   | (string & {});

package/src/gateway-provider-options.ts

@@ -22,7 +22,7 @@ export type GatewayProviderOptions = {
   has?: Array<'implicit-caching' | 'vision'>;
 
   /**
-   * Idempotency key for `experimental_startTextBatch`: retries with the same
+   * Idempotency key for `experimental_startBatch`: retries with the same
    * key replay the original batch instead of creating a duplicate.
    */
   idempotencyKey?: string;

package/src/gateway-provider.ts

@@ -31,7 +31,8 @@ import {
   type GatewayGenerationInfoParams,
   type GatewayGenerationInfo,
 } from './gateway-generation-info';
-import { GatewayBatchLanguageModel } from './gateway-language-model-batch';
+import { GatewayBatch } from './gateway-batch';
+import { GatewayLanguageModel } from './gateway-language-model';
 import { GatewayEmbeddingModel } from './gateway-embedding-model';
 import { GatewayImageModel } from './gateway-image-model';
 import { GatewayVideoModel } from './gateway-video-model';
@@ -54,7 +55,7 @@ import { getVercelOidcToken, getVercelRequestId } from './vercel-environment';
 import type { GatewayModelId } from './gateway-language-model-settings';
 import type {
   EmbeddingModelV4,
-  Experimental_BatchLanguageModelV4 as BatchLanguageModelV4,
+  Experimental_BatchV4 as BatchV4,
   ImageModelV4,
   RerankingModelV4,
   SpeechModelV4,
@@ -63,21 +64,25 @@ import type {
   Experimental_RealtimeFactoryV4 as RealtimeFactoryV4,
   Experimental_RealtimeFactoryV4GetTokenOptions as RealtimeFactoryV4GetTokenOptions,
   ProviderV4,
+  LanguageModelV4,
 } from '@ai-sdk/provider';
 import { VERSION } from './version';
 
 export interface GatewayProvider extends ProviderV4 {
-  (modelId: GatewayModelId): BatchLanguageModelV4;
+  (modelId: GatewayModelId): LanguageModelV4;
 
   /**
    * Creates a model for text generation.
    */
-  chat(modelId: GatewayModelId): BatchLanguageModelV4;
+  chat(modelId: GatewayModelId): LanguageModelV4;
 
   /**
    * Creates a model for text generation.
    */
-  languageModel(modelId: GatewayModelId): BatchLanguageModelV4;
+  languageModel(modelId: GatewayModelId): LanguageModelV4;
+
+  /** Returns a BatchV4 interface for processing batches with AI Gateway. */
+  experimental_batch(): BatchV4<{ text: GatewayModelId }>;
 
   /**
    * Returns available providers and models for use with the remote provider.
@@ -417,7 +422,7 @@ export function createGateway(
   };
 
   const createLanguageModel = (modelId: GatewayModelId) => {
-    return new GatewayBatchLanguageModel(modelId, {
+    return new GatewayLanguageModel(modelId, {
       provider: 'gateway',
       baseURL,
       headers: getHeaders,
@@ -426,6 +431,15 @@ export function createGateway(
     });
   };
 
+  const createBatch = () =>
+    new GatewayBatch({
+      provider: 'gateway',
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+      o11yHeaders: createO11yHeaders(),
+    });
+
   const getAvailableModels = async () => {
     const now = options._internal?.currentDate?.().getTime() ?? Date.now();
     if (!pendingMetadata || now - lastFetchTime > cacheRefreshMillis) {
@@ -522,6 +536,7 @@ export function createGateway(
     });
   };
   provider.languageModel = createLanguageModel;
+  provider.experimental_batch = createBatch;
   const createEmbeddingModel = (modelId: GatewayEmbeddingModelId) => {
     return new GatewayEmbeddingModel(modelId, {
       provider: 'gateway',