@ai-sdk/xai 4.0.53 → 4.0.55

package/docs/01-xai.mdx

@@ -641,27 +641,37 @@ import { xai } from '@ai-sdk/xai';
 import {
   experimental_getBatchResults as getBatchResults,
   experimental_getBatchStatus as getBatchStatus,
-  experimental_startTextBatch as startTextBatch,
+  experimental_startBatch as startBatch,
 } from 'ai';
 import { setTimeout } from 'node:timers/promises';
 
-const model = xai('grok-4.3');
+const model = 'grok-4.3';
 
-const batch = await startTextBatch({
-  model,
+const batch = await startBatch({
+  provider: xai,
   requests: [
-    { id: 'capital-france', prompt: 'What is the capital of France?' },
-    { id: 'capital-germany', prompt: 'What is the capital of Germany?' },
+    {
+      id: 'capital-france',
+      type: 'text',
+      model,
+      prompt: 'What is the capital of France?',
+    },
+    {
+      id: 'capital-germany',
+      type: 'text',
+      model: 'grok-4.20-non-reasoning',
+      prompt: 'What is the capital of Germany?',
+    },
   ],
 });
 
 let status = batch.status;
 while (status === 'pending') {
   await setTimeout(60_000);
-  ({ status } = await getBatchStatus({ model, batch }));
+  ({ status } = await getBatchStatus({ provider: xai, batch }));
 }
 
-for await (const item of getBatchResults({ model, batch })) {
+for await (const item of getBatchResults({ provider: xai, batch })) {
   if (item.status === 'succeeded') {
     console.log(item.id, item.text);
   } else {
@@ -670,14 +680,13 @@ for await (const item of getBatchResults({ model, batch })) {
 }
 ```
 
-`startTextBatch` returns a serializable batch reference. Persist this reference
+`startBatch` returns a serializable batch reference. Persist this reference
 to check the batch status or retrieve its results from another process. Results
 can arrive in a different order from the input requests, so match each result by
 its `id`.
 
-Text batches are available through `xai(modelId)` and
-`xai.responses(modelId)`. The legacy `xai.chat(modelId)` models do not expose
-the batch APIs.
+Each request specifies its `type` and `model`. xAI supports using different
+text models within the same batch.
 
 <Note>
   The xAI Batch API does not support per-batch webhooks. When you provide a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/xai",
-  "version": "4.0.53",
+  "version": "4.0.55",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -29,8 +29,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "4.0.10",
-    "@ai-sdk/provider-utils": "5.0.36"
+    "@ai-sdk/provider": "4.0.11",
+    "@ai-sdk/provider-utils": "5.0.37"
   },
   "devDependencies": {
     "@ai-sdk/test-server": "2.0.1",

package/src/responses/xai-responses-language-model.ts

@@ -139,6 +139,15 @@ function isRetryableStatusCode(statusCode: number): boolean {
   );
 }
 
+export const xaiResponsesSupportedUrls: Record<string, RegExp[]> = {
+  'image/*': [/^https?:\/\/.*$/],
+  // xAI's Responses API accepts non-image documents (PDF, plain text, CSV, etc.) as
+  // `{ type: 'input_file', file_url }`. Keeping these URLs intact here lets them pass
+  // through to the converter instead of being downloaded to bytes by the SDK.
+  'application/pdf': [/^https?:\/\/.*$/],
+  'text/*': [/^https?:\/\/.*$/],
+};
+
 export class XaiResponsesLanguageModel implements LanguageModelV4 {
   readonly specificationVersion = 'v4';
 
@@ -169,31 +178,30 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
     return this.config.provider;
   }
 
-  readonly supportedUrls: Record<string, RegExp[]> = {
-    'image/*': [/^https?:\/\/.*$/],
-    // xAI's Responses API accepts non-image documents (PDF, plain text, CSV, etc.) as
-    // `{ type: 'input_file', file_url }`. Keeping these URLs intact here lets them pass
-    // through to the converter instead of being downloaded to bytes by the SDK.
-    'application/pdf': [/^https?:\/\/.*$/],
-    'text/*': [/^https?:\/\/.*$/],
-  };
-
-  protected async getArgs({
-    prompt,
-    maxOutputTokens,
-    temperature,
-    topP,
-    topK,
-    frequencyPenalty,
-    presencePenalty,
-    stopSequences,
-    seed,
-    responseFormat,
-    providerOptions,
-    tools,
-    toolChoice,
-    reasoning,
-  }: LanguageModelV4CallOptions) {
+  readonly supportedUrls = xaiResponsesSupportedUrls;
+
+  static async prepareRequest({
+    modelId,
+    options: {
+      prompt,
+      maxOutputTokens,
+      temperature,
+      topP,
+      topK,
+      frequencyPenalty,
+      presencePenalty,
+      stopSequences,
+      seed,
+      responseFormat,
+      providerOptions,
+      tools,
+      toolChoice,
+      reasoning,
+    },
+  }: {
+    modelId: XaiResponsesModelId;
+    options: LanguageModelV4CallOptions;
+  }) {
     const warnings: SharedV4Warning[] = [];
 
     const options =
@@ -276,7 +284,7 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
 
     let resolvedReasoningEffort = options.reasoningEffort;
     if (resolvedReasoningEffort == null && isCustomReasoning(reasoning)) {
-      if (!supportsReasoningEffort(this.modelId)) {
+      if (!supportsReasoningEffort(modelId)) {
         warnings.push({
           type: 'unsupported',
           feature: 'reasoning',
@@ -292,7 +300,7 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
             low: 'low',
             medium: 'medium',
             high: 'high',
-            xhigh: this.modelId === 'grok-4.6' ? 'xhigh' : 'high',
+            xhigh: modelId === 'grok-4.6' ? 'xhigh' : 'high',
           },
           warnings,
         });
@@ -300,7 +308,7 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
     }
 
     const baseArgs: Record<string, unknown> = {
-      model: this.modelId,
+      model: modelId,
       input,
       logprobs:
         options.logprobs === true || options.topLogprobs != null
@@ -370,6 +378,13 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
     };
   }
 
+  private getArgs(options: LanguageModelV4CallOptions) {
+    return XaiResponsesLanguageModel.prepareRequest({
+      modelId: this.modelId,
+      options,
+    });
+  }
+
   async doGenerate(
     options: LanguageModelV4CallOptions,
   ): Promise<LanguageModelV4GenerateResult> {

package/src/{responses/xai-responses-batch.ts → xai-batch.ts}

@@ -1,12 +1,14 @@
 import {
   InvalidArgumentError,
-  type Experimental_BatchLanguageModelV4 as BatchLanguageModelV4,
+  type Experimental_BatchV4 as BatchV4,
   type Experimental_BatchV4Error as BatchV4Error,
   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_TextBatchV4Request as TextBatchV4Request,
+  type Experimental_TextBatchV4ItemResult as TextBatchV4ItemResult,
+  type Experimental_BatchV4StartOptions as BatchV4StartOptions,
   type LanguageModelV4Content,
   type LanguageModelV4GenerateResult,
   type SharedV4ProviderMetadata,
@@ -20,37 +22,54 @@ import {
   getFromApi,
   lazySchema,
   normalizeBatchRequestCounts,
+  parseProviderOptions,
   postFormDataToApi,
   postJsonToApi,
   safeValidateTypes,
-  WORKFLOW_DESERIALIZE,
-  WORKFLOW_SERIALIZE,
   zodSchema,
   type InferSchema,
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
-import { convertXaiChatUsage } from '../convert-xai-chat-usage';
-import { getResponseMetadata } from '../get-response-metadata';
-import { mapXaiFinishReason } from '../map-xai-finish-reason';
+import { convertXaiChatUsage } from './convert-xai-chat-usage';
+import { getResponseMetadata } from './get-response-metadata';
+import { mapXaiFinishReason } from './map-xai-finish-reason';
 import {
   xaiChatResponseSchema,
   type XaiChatResponse,
-} from '../xai-chat-language-model';
-import { xaiFailedResponseHandler } from '../xai-error';
-import { xaiFilesResponseSchema } from '../files/xai-files-api';
+} from './xai-chat-language-model';
+import { xaiFailedResponseHandler } from './xai-error';
+import { xaiFilesResponseSchema } from './files/xai-files-api';
 import {
   XaiResponsesLanguageModel,
+  xaiResponsesSupportedUrls,
   type XaiResponsesConfig,
-} from './xai-responses-language-model';
-import type { XaiResponsesModelId } from './xai-responses-language-model-options';
+} from './responses/xai-responses-language-model';
+import type { XaiResponsesModelId } from './responses/xai-responses-language-model-options';
 
 const xaiBatchEndpoint = '/v1/responses';
 const xaiBatchName = 'ai-sdk-text-batch';
 const xaiBatchResultsPageSize = 1000;
 
-type XaiBatchRequest = Parameters<
-  BatchLanguageModelV4['experimental_doStartBatch']
->[0]['requests'][number];
+const xaiBatchProviderOptionsSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      /**
+       * TTL in seconds for the uploaded batch input file, measured from
+       * upload time. xAI accepts integers between 3600 (1 hour) and
+       * 2592000 (30 days) inclusive. Without it the file has no expiry.
+       */
+      inputFileExpiresAfter: z
+        .number()
+        .int()
+        .min(3600)
+        .max(2_592_000)
+        .optional(),
+    }),
+  ),
+);
+
+type XaiBatchModelIds = { readonly text: XaiResponsesModelId };
+type XaiBatchRequest = TextBatchV4Request<XaiResponsesModelId>;
 
 type XaiBatchPreparedRequest = {
   body: unknown;
@@ -116,18 +135,22 @@ const xaiBatchResultsPageSchema = lazySchema(() =>
   ),
 );
 
-class XaiResponsesBatch {
+export class XaiBatch implements BatchV4<XaiBatchModelIds> {
+  readonly specificationVersion = 'v4' as const;
+  readonly provider: string;
+  readonly supportedUrls = xaiResponsesSupportedUrls;
+
   constructor(
     private readonly options: {
+      provider: string;
       config: XaiResponsesConfig;
-      prepareRequest: (
-        request: XaiBatchRequest,
-      ) => PromiseLike<XaiBatchPreparedRequest>;
     },
-  ) {}
+  ) {
+    this.provider = options.provider;
+  }
 
-  async startBatch(
-    options: BatchV4StartOptions<XaiBatchRequest>,
+  async doStartBatch(
+    options: BatchV4StartOptions<XaiBatchModelIds>,
   ): Promise<BatchV4StartResult> {
     const fileParts: string[] = [];
     const warnings: BatchV4StartResult['warnings'] =
@@ -144,8 +167,14 @@ class XaiResponsesBatch {
             },
           ];
 
+    const batchOptions = await parseProviderOptions({
+      provider: 'xai',
+      providerOptions: options.providerOptions,
+      schema: xaiBatchProviderOptionsSchema,
+    });
+
     for (const request of options.requests) {
-      const preparedRequest = await this.options.prepareRequest(request);
+      const preparedRequest = await this.prepareRequest(request);
 
       fileParts.push(
         JSON.stringify({
@@ -166,6 +195,14 @@ class XaiResponsesBatch {
     const file = new Blob(fileParts, { type: 'application/jsonl' });
     fileParts.length = 0;
     const formData = new FormData();
+    // xAI rejects uploads where expires_after arrives after the file part,
+    // so all fields precede the file.
+    if (batchOptions?.inputFileExpiresAfter != null) {
+      formData.append(
+        'expires_after',
+        String(batchOptions.inputFileExpiresAfter),
+      );
+    }
     formData.append('file', file, filename);
 
     const headers = combineHeaders(
@@ -203,19 +240,31 @@ class XaiResponsesBatch {
     return {
       batchId: batch.batch_id,
       ...convertXaiBatchStatus(batch),
+      providerMetadata: {
+        xai: {
+          inputFileId: uploadedFile.id,
+          ...(uploadedFile.expires_at != null
+            ? {
+                inputFileExpiresAt: new Date(
+                  uploadedFile.expires_at * 1000,
+                ).toISOString(),
+              }
+            : {}),
+        },
+      },
       warnings,
     };
   }
 
-  async getBatchStatus(
+  async doGetBatchStatus(
     options: BatchV4OperationOptions,
   ): Promise<BatchV4Status> {
     return convertXaiBatchStatus(await this.retrieveBatch(options));
   }
 
-  async getBatchResults(
+  async doGetBatchResults(
     options: BatchV4OperationOptions,
-  ): Promise<ReadableStream<BatchV4ItemResult<LanguageModelV4GenerateResult>>> {
+  ): Promise<ReadableStream<BatchV4ItemResult>> {
     const batch = await this.retrieveBatch(options);
     if (convertXaiBatchStatus(batch).status === 'pending') {
       throw new InvalidArgumentError({
@@ -249,7 +298,7 @@ class XaiResponsesBatch {
 
   private async *iterateBatchResults(
     options: BatchV4OperationOptions,
-  ): AsyncGenerator<BatchV4ItemResult<LanguageModelV4GenerateResult>> {
+  ): AsyncGenerator<BatchV4ItemResult> {
     let paginationToken: string | undefined;
 
     do {
@@ -287,7 +336,7 @@ class XaiResponsesBatch {
 
   private async convertBatchResult(
     result: XaiBatchResult,
-  ): Promise<BatchV4ItemResult<LanguageModelV4GenerateResult>> {
+  ): Promise<TextBatchV4ItemResult> {
     const error = result.batch_result?.error;
     if (
       (result.error_message?.length ?? 0) > 0 ||
@@ -296,6 +345,7 @@ class XaiResponsesBatch {
     ) {
       const convertedError = convertXaiBatchError(result);
       return {
+        type: 'text',
         id: result.batch_request_id,
         status: isXaiCancellationError(error?.code) ? 'cancelled' : 'failed',
         error: convertedError,
@@ -317,11 +367,13 @@ class XaiResponsesBatch {
       const conversion = convertXaiChatBatchResponse(validation.value);
       return conversion.success
         ? {
+            type: 'text',
             id: result.batch_request_id,
             status: 'succeeded',
             result: conversion.result,
           }
         : {
+            type: 'text',
             id: result.batch_request_id,
             status: 'failed',
             error: conversion.error,
@@ -331,51 +383,19 @@ class XaiResponsesBatch {
     return invalidXaiBatchResult(result.batch_request_id);
   }
 
-  private getUrl(path: string) {
-    return `${this.options.config.baseURL ?? 'https://api.x.ai/v1'}${path}`;
-  }
-}
-
-export class XaiResponsesBatchLanguageModel
-  extends XaiResponsesLanguageModel
-  implements BatchLanguageModelV4
-{
-  private readonly batch: XaiResponsesBatch;
-
-  static [WORKFLOW_SERIALIZE](model: XaiResponsesLanguageModel) {
-    return XaiResponsesLanguageModel[WORKFLOW_SERIALIZE](model);
-  }
-
-  static [WORKFLOW_DESERIALIZE](options: {
-    modelId: XaiResponsesModelId;
-    config: XaiResponsesConfig;
-  }) {
-    return new XaiResponsesBatchLanguageModel(options.modelId, options.config);
-  }
-
-  constructor(modelId: XaiResponsesModelId, config: XaiResponsesConfig) {
-    super(modelId, config);
-    this.batch = new XaiResponsesBatch({
-      config,
-      prepareRequest: async request => {
-        const { args: body, warnings } = await this.getArgs(request.options);
-        return { body, warnings };
-      },
-    });
-  }
-
-  experimental_doStartBatch(
-    options: Parameters<BatchLanguageModelV4['experimental_doStartBatch']>[0],
-  ) {
-    return this.batch.startBatch(options);
-  }
-
-  experimental_doGetBatchStatus(options: BatchV4OperationOptions) {
-    return this.batch.getBatchStatus(options);
+  private async prepareRequest(
+    request: XaiBatchRequest,
+  ): Promise<XaiBatchPreparedRequest> {
+    const { args: body, warnings } =
+      await XaiResponsesLanguageModel.prepareRequest({
+        modelId: request.modelId,
+        options: request.options,
+      });
+    return { body, warnings };
   }
 
-  experimental_doGetBatchResults(options: BatchV4OperationOptions) {
-    return this.batch.getBatchResults(options);
+  private getUrl(path: string) {
+    return `${this.options.config.baseURL ?? 'https://api.x.ai/v1'}${path}`;
   }
 }
 
@@ -455,10 +475,9 @@ function isXaiCancellationError(code: string | number | null | undefined) {
   );
 }
 
-function invalidXaiBatchResult(
-  id: string,
-): BatchV4ItemResult<LanguageModelV4GenerateResult> {
+function invalidXaiBatchResult(id: string): TextBatchV4ItemResult {
   return {
+    type: 'text',
     id,
     status: 'failed',
     error: {

package/src/xai-provider.ts

@@ -2,7 +2,7 @@ import {
   type Experimental_RealtimeFactoryV4 as RealtimeFactoryV4,
   type Experimental_RealtimeFactoryV4GetTokenOptions as RealtimeFactoryV4GetTokenOptions,
   type Experimental_VideoModelV4,
-  type Experimental_BatchLanguageModelV4 as BatchLanguageModelV4,
+  type Experimental_BatchV4 as BatchV4,
   type FilesV4,
   type ImageModelV4,
   type LanguageModelV4,
@@ -23,7 +23,8 @@ import { XaiChatLanguageModel } from './xai-chat-language-model';
 import type { XaiChatModelId } from './xai-chat-language-model-options';
 import { XaiImageModel } from './xai-image-model';
 import type { XaiImageModelId } from './xai-image-settings';
-import { XaiResponsesBatchLanguageModel } from './responses/xai-responses-batch';
+import { XaiBatch } from './xai-batch';
+import { XaiResponsesLanguageModel } from './responses/xai-responses-language-model';
 import type { XaiResponsesModelId } from './responses/xai-responses-language-model-options';
 import { XaiRealtimeModel } from './realtime/xai-realtime-model';
 import { xaiTools } from './tool';
@@ -35,12 +36,12 @@ import { XaiSpeechModel } from './xai-speech-model';
 import { XaiTranscriptionModel } from './xai-transcription-model';
 
 export interface XaiProvider extends ProviderV4 {
-  (modelId: XaiResponsesModelId): BatchLanguageModelV4;
+  (modelId: XaiResponsesModelId): LanguageModelV4;
 
   /**
    * Creates an Xai language model for text generation.
    */
-  languageModel(modelId: XaiResponsesModelId): BatchLanguageModelV4;
+  languageModel(modelId: XaiResponsesModelId): LanguageModelV4;
 
   /**
    * Creates an Xai chat model for text generation.
@@ -50,7 +51,12 @@ export interface XaiProvider extends ProviderV4 {
   /**
    * Creates an Xai responses model for text generation.
    */
-  responses: (modelId: XaiResponsesModelId) => BatchLanguageModelV4;
+  responses: (modelId: XaiResponsesModelId) => LanguageModelV4;
+
+  /**
+   * Returns a BatchV4 interface for processing batches with xAI.
+   */
+  experimental_batch(): BatchV4<{ text: XaiResponsesModelId }>;
 
   /**
    * Creates an Xai image model for image generation.
@@ -167,7 +173,7 @@ export function createXai(options: XaiProviderSettings = {}): XaiProvider {
   };
 
   const createResponsesLanguageModel = (modelId: XaiResponsesModelId) => {
-    return new XaiResponsesBatchLanguageModel(modelId, {
+    return new XaiResponsesLanguageModel(modelId, {
       provider: 'xai.responses',
       baseURL,
       headers: getHeaders,
@@ -249,6 +255,18 @@ export function createXai(options: XaiProviderSettings = {}): XaiProvider {
       fetch: options.fetch,
     });
 
+  const createBatch = () =>
+    new XaiBatch({
+      provider: 'xai.batch',
+      config: {
+        provider: 'xai.responses',
+        baseURL,
+        headers: getHeaders,
+        generateId,
+        fetch: options.fetch,
+      },
+    });
+
   const provider = (modelId: XaiResponsesModelId) =>
     createResponsesLanguageModel(modelId);
 
@@ -270,6 +288,7 @@ export function createXai(options: XaiProviderSettings = {}): XaiProvider {
   provider.transcriptionModel = createTranscriptionModel;
   provider.transcription = createTranscriptionModel;
   provider.files = createFiles;
+  provider.experimental_batch = createBatch;
   provider.tools = xaiTools;
 
   return provider;