@ai-sdk/xai 4.0.54 → 4.0.56

package/docs/01-xai.mdx

@@ -625,59 +625,19 @@ The following provider options are available:
   tools with client-side function tools in the same request.
 </Note>
 
-## 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>
 
-The xAI provider supports asynchronous text generation through the
-[Batch API](https://docs.x.ai/developers/advanced-api-usage/batch-api). Use the
-experimental text batch APIs to start a batch, poll its status, and stream its
-results:
+The xAI provider supports asynchronous text generation through the [Batch
+API](https://docs.x.ai/developers/advanced-api-usage/batch-api). Pass the xAI
+provider to the AI SDK's [Batch](/docs/ai-sdk-core/batch) API
+for the complete workflow, including polling, persistence, and result handling.
 
-```ts
-import { xai } from '@ai-sdk/xai';
-import {
-  experimental_getBatchResults as getBatchResults,
-  experimental_getBatchStatus as getBatchStatus,
-  experimental_startTextBatch as startTextBatch,
-} from 'ai';
-import { setTimeout } from 'node:timers/promises';
-
-const model = xai('grok-4.3');
-
-const batch = await startTextBatch({
-  model,
-  requests: [
-    { id: 'capital-france', prompt: 'What is the capital of France?' },
-    { id: 'capital-germany', prompt: 'What is the capital of Germany?' },
-  ],
-});
-
-let status = batch.status;
-while (status === 'pending') {
-  await setTimeout(60_000);
-  ({ status } = await getBatchStatus({ model, batch }));
-}
-
-for await (const item of getBatchResults({ model, batch })) {
-  if (item.status === 'succeeded') {
-    console.log(item.id, item.text);
-  } else {
-    console.error(item.id, item.error);
-  }
-}
-```
-
-`startTextBatch` 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.54",
+  "version": "4.0.56",
   "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.12",
+    "@ai-sdk/provider-utils": "5.0.38"
   },
   "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,
@@ -24,26 +26,25 @@ import {
   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';
@@ -67,9 +68,8 @@ const xaiBatchProviderOptionsSchema = lazySchema(() =>
   ),
 );
 
-type XaiBatchRequest = Parameters<
-  BatchLanguageModelV4['experimental_doStartBatch']
->[0]['requests'][number];
+type XaiBatchModelIds = { readonly text: XaiResponsesModelId };
+type XaiBatchRequest = TextBatchV4Request<XaiResponsesModelId>;
 
 type XaiBatchPreparedRequest = {
   body: unknown;
@@ -135,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'] =
@@ -170,7 +174,7 @@ class XaiResponsesBatch {
     });
 
     for (const request of options.requests) {
-      const preparedRequest = await this.options.prepareRequest(request);
+      const preparedRequest = await this.prepareRequest(request);
 
       fileParts.push(
         JSON.stringify({
@@ -252,15 +256,15 @@ class XaiResponsesBatch {
     };
   }
 
-  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({
@@ -294,7 +298,7 @@ class XaiResponsesBatch {
 
   private async *iterateBatchResults(
     options: BatchV4OperationOptions,
-  ): AsyncGenerator<BatchV4ItemResult<LanguageModelV4GenerateResult>> {
+  ): AsyncGenerator<BatchV4ItemResult> {
     let paginationToken: string | undefined;
 
     do {
@@ -332,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 ||
@@ -341,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,
@@ -362,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,
@@ -376,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}`;
   }
 }
 
@@ -500,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;