@ai-sdk/xai 4.0.0-beta.4 → 4.0.0-beta.40

package/src/xai-image-model.ts

@@ -1,4 +1,4 @@
-import { ImageModelV3, SharedV3Warning } from '@ai-sdk/provider';
+import { ImageModelV4, SharedV4Warning } from '@ai-sdk/provider';
 import {
   combineHeaders,
   convertImageModelFileToDataUri,
@@ -9,6 +9,9 @@ import {
   getFromApi,
   parseProviderOptions,
   postJsonToApi,
+  serializeModelOptions,
+  WORKFLOW_SERIALIZE,
+  WORKFLOW_DESERIALIZE,
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 import { xaiFailedResponseHandler } from './xai-error';
@@ -18,21 +21,35 @@ import { XaiImageModelId } from './xai-image-settings';
 interface XaiImageModelConfig {
   provider: string;
   baseURL: string | undefined;
-  headers: () => Record<string, string | undefined>;
+  headers?: () => Record<string, string | undefined>;
   fetch?: FetchFunction;
   _internal?: {
     currentDate?: () => Date;
   };
 }
 
-export class XaiImageModel implements ImageModelV3 {
-  readonly specificationVersion = 'v3';
+export class XaiImageModel implements ImageModelV4 {
+  readonly specificationVersion = 'v4';
   readonly maxImagesPerCall = 3;
 
   get provider(): string {
     return this.config.provider;
   }
 
+  static [WORKFLOW_SERIALIZE](model: XaiImageModel) {
+    return serializeModelOptions({
+      modelId: model.modelId,
+      config: model.config,
+    });
+  }
+
+  static [WORKFLOW_DESERIALIZE](options: {
+    modelId: XaiImageModelId;
+    config: XaiImageModelConfig;
+  }) {
+    return new XaiImageModel(options.modelId, options.config);
+  }
+
   constructor(
     readonly modelId: XaiImageModelId,
     private config: XaiImageModelConfig,
@@ -49,10 +66,10 @@ export class XaiImageModel implements ImageModelV3 {
     abortSignal,
     files,
     mask,
-  }: Parameters<ImageModelV3['doGenerate']>[0]): Promise<
-    Awaited<ReturnType<ImageModelV3['doGenerate']>>
+  }: Parameters<ImageModelV4['doGenerate']>[0]): Promise<
+    Awaited<ReturnType<ImageModelV4['doGenerate']>>
   > {
-    const warnings: Array<SharedV3Warning> = [];
+    const warnings: Array<SharedV4Warning> = [];
 
     if (size != null) {
       warnings.push({
@@ -135,7 +152,7 @@ export class XaiImageModel implements ImageModelV3 {
     const currentDate = this.config._internal?.currentDate?.() ?? new Date();
     const { value: response, responseHeaders } = await postJsonToApi({
       url: `${baseURL}${endpoint}`,
-      headers: combineHeaders(this.config.headers(), headers),
+      headers: combineHeaders(this.config.headers?.(), headers),
       body,
       failedResponseHandler: xaiFailedResponseHandler,
       successfulResponseHandler: createJsonResponseHandler(

package/src/xai-image-settings.ts

@@ -1,6 +1,4 @@
 export type XaiImageModelId =
-  | 'grok-2-image'
-  | 'grok-2-image-1212'
   | 'grok-imagine-image'
   | 'grok-imagine-image-pro'
   | (string & {});

package/src/xai-prepare-tools.ts

@@ -1,6 +1,6 @@
 import {
-  LanguageModelV3CallOptions,
-  SharedV3Warning,
+  LanguageModelV4CallOptions,
+  SharedV4Warning,
   UnsupportedFunctionalityError,
 } from '@ai-sdk/provider';
 import { XaiToolChoice } from './xai-chat-prompt';
@@ -9,8 +9,8 @@ export function prepareTools({
   tools,
   toolChoice,
 }: {
-  tools: LanguageModelV3CallOptions['tools'];
-  toolChoice?: LanguageModelV3CallOptions['toolChoice'];
+  tools: LanguageModelV4CallOptions['tools'];
+  toolChoice?: LanguageModelV4CallOptions['toolChoice'];
 }): {
   tools:
     | Array<{
@@ -24,12 +24,12 @@ export function prepareTools({
       }>
     | undefined;
   toolChoice: XaiToolChoice | undefined;
-  toolWarnings: SharedV3Warning[];
+  toolWarnings: SharedV4Warning[];
 } {
   // when the tools array is empty, change it to undefined to prevent errors
   tools = tools?.length ? tools : undefined;
 
-  const toolWarnings: SharedV3Warning[] = [];
+  const toolWarnings: SharedV4Warning[] = [];
 
   if (tools == null) {
     return { tools: undefined, toolChoice: undefined, toolWarnings };

package/src/xai-provider.ts

@@ -1,9 +1,10 @@
 import {
-  type Experimental_VideoModelV3,
-  ImageModelV3,
-  LanguageModelV3,
+  type Experimental_VideoModelV4,
+  FilesV4,
+  ImageModelV4,
+  LanguageModelV4,
   NoSuchModelError,
-  ProviderV3,
+  ProviderV4,
 } from '@ai-sdk/provider';
 import {
   FetchFunction,
@@ -20,49 +21,52 @@ import { XaiResponsesLanguageModel } from './responses/xai-responses-language-mo
 import { XaiResponsesModelId } from './responses/xai-responses-options';
 import { xaiTools } from './tool';
 import { VERSION } from './version';
+import { XaiFiles } from './files/xai-files';
 import { XaiVideoModel } from './xai-video-model';
 import { XaiVideoModelId } from './xai-video-settings';
 
-export interface XaiProvider extends ProviderV3 {
-  /**
-   * Creates an Xai chat model for text generation.
-   */
-  (modelId: XaiChatModelId): LanguageModelV3;
+export interface XaiProvider extends ProviderV4 {
+  (modelId: XaiResponsesModelId): LanguageModelV4;
 
   /**
    * Creates an Xai language model for text generation.
    */
-  languageModel(modelId: XaiChatModelId): LanguageModelV3;
+  languageModel(modelId: XaiResponsesModelId): LanguageModelV4;
 
   /**
    * Creates an Xai chat model for text generation.
    */
-  chat: (modelId: XaiChatModelId) => LanguageModelV3;
+  chat: (modelId: XaiChatModelId) => LanguageModelV4;
 
   /**
-   * Creates an Xai responses model for agentic tool calling.
+   * Creates an Xai responses model for text generation.
    */
-  responses: (modelId: XaiResponsesModelId) => LanguageModelV3;
+  responses: (modelId: XaiResponsesModelId) => LanguageModelV4;
 
   /**
    * Creates an Xai image model for image generation.
    */
-  image(modelId: XaiImageModelId): ImageModelV3;
+  image(modelId: XaiImageModelId): ImageModelV4;
 
   /**
    * Creates an Xai image model for image generation.
    */
-  imageModel(modelId: XaiImageModelId): ImageModelV3;
+  imageModel(modelId: XaiImageModelId): ImageModelV4;
 
   /**
    * Creates an Xai video model for video generation.
    */
-  video(modelId: XaiVideoModelId): Experimental_VideoModelV3;
+  video(modelId: XaiVideoModelId): Experimental_VideoModelV4;
 
   /**
    * Creates an Xai video model for video generation.
    */
-  videoModel(modelId: XaiVideoModelId): Experimental_VideoModelV3;
+  videoModel(modelId: XaiVideoModelId): Experimental_VideoModelV4;
+
+  /**
+   * Returns the xAI files interface for uploading files.
+   */
+  files(): FilesV4;
 
   /**
    * Server-side agentic tools for use with the responses API.
@@ -153,11 +157,19 @@ export function createXai(options: XaiProviderSettings = {}): XaiProvider {
     });
   };
 
-  const provider = (modelId: XaiChatModelId) =>
-    createChatLanguageModel(modelId);
+  const createFiles = () =>
+    new XaiFiles({
+      provider: 'xai.files',
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
+  const provider = (modelId: XaiResponsesModelId) =>
+    createResponsesLanguageModel(modelId);
 
-  provider.specificationVersion = 'v3' as const;
-  provider.languageModel = createChatLanguageModel;
+  provider.specificationVersion = 'v4' as const;
+  provider.languageModel = createResponsesLanguageModel;
   provider.chat = createChatLanguageModel;
   provider.responses = createResponsesLanguageModel;
   provider.embeddingModel = (modelId: string) => {
@@ -168,6 +180,7 @@ export function createXai(options: XaiProviderSettings = {}): XaiProvider {
   provider.image = createImageModel;
   provider.videoModel = createVideoModel;
   provider.video = createVideoModel;
+  provider.files = createFiles;
   provider.tools = xaiTools;
 
   return provider;

package/src/xai-video-model.ts

@@ -1,7 +1,7 @@
 import {
   AISDKError,
-  type Experimental_VideoModelV3,
-  type SharedV3Warning,
+  type Experimental_VideoModelV4,
+  type SharedV4Warning,
 } from '@ai-sdk/provider';
 import {
   combineHeaders,
@@ -16,7 +16,7 @@ import {
 import { z } from 'zod/v4';
 import { xaiFailedResponseHandler } from './xai-error';
 import {
-  type XaiVideoModelOptions,
+  type XaiParsedVideoModelOptions,
   xaiVideoModelOptionsSchema,
 } from './xai-video-options';
 import type { XaiVideoModelId } from './xai-video-settings';
@@ -37,8 +37,29 @@ const RESOLUTION_MAP: Record<string, string> = {
   '640x480': '480p',
 };
 
-export class XaiVideoModel implements Experimental_VideoModelV3 {
-  readonly specificationVersion = 'v3';
+function resolveVideoMode(
+  options: XaiParsedVideoModelOptions | undefined,
+): XaiParsedVideoModelOptions['mode'] | undefined {
+  if (options?.mode != null) {
+    return options.mode;
+  }
+
+  if (options?.videoUrl != null) {
+    return 'edit-video';
+  }
+
+  if (
+    options?.referenceImageUrls != null &&
+    options.referenceImageUrls.length > 0
+  ) {
+    return 'reference-to-video';
+  }
+
+  return undefined;
+}
+
+export class XaiVideoModel implements Experimental_VideoModelV4 {
+  readonly specificationVersion = 'v4';
   readonly maxVideosPerCall = 1;
 
   get provider(): string {
@@ -51,18 +72,22 @@ export class XaiVideoModel implements Experimental_VideoModelV3 {
   ) {}
 
   async doGenerate(
-    options: Parameters<Experimental_VideoModelV3['doGenerate']>[0],
-  ): Promise<Awaited<ReturnType<Experimental_VideoModelV3['doGenerate']>>> {
+    options: Parameters<Experimental_VideoModelV4['doGenerate']>[0],
+  ): Promise<Awaited<ReturnType<Experimental_VideoModelV4['doGenerate']>>> {
     const currentDate = this.config._internal?.currentDate?.() ?? new Date();
-    const warnings: SharedV3Warning[] = [];
+    const warnings: SharedV4Warning[] = [];
 
     const xaiOptions = (await parseProviderOptions({
       provider: 'xai',
       providerOptions: options.providerOptions,
       schema: xaiVideoModelOptionsSchema,
-    })) as XaiVideoModelOptions | undefined;
+    })) as XaiParsedVideoModelOptions | undefined;
+
+    const effectiveMode = resolveVideoMode(xaiOptions);
 
-    const isEdit = xaiOptions?.videoUrl != null;
+    const isEdit = effectiveMode === 'edit-video';
+    const isExtension = effectiveMode === 'extend-video';
+    const hasReferenceImages = effectiveMode === 'reference-to-video';
 
     if (options.fps != null) {
       warnings.push({
@@ -90,6 +115,7 @@ export class XaiVideoModel implements Experimental_VideoModelV3 {
       });
     }
 
+    // Edit mode: duration, aspectRatio, resolution not supported
     if (isEdit && options.duration != null) {
       warnings.push({
         type: 'unsupported',
@@ -117,22 +143,46 @@ export class XaiVideoModel implements Experimental_VideoModelV3 {
       });
     }
 
+    // Extension mode: aspectRatio and resolution not supported
+    if (isExtension && options.aspectRatio != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'aspectRatio',
+        details: 'xAI video extension does not support custom aspect ratio.',
+      });
+    }
+
+    if (
+      isExtension &&
+      (xaiOptions?.resolution != null || options.resolution != null)
+    ) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'resolution',
+        details: 'xAI video extension does not support custom resolution.',
+      });
+    }
+
     const body: Record<string, unknown> = {
       model: this.modelId,
       prompt: options.prompt,
     };
 
-    if (!isEdit && options.duration != null) {
+    const allowDuration = !isEdit;
+    const allowAspectRatio = !isEdit && !isExtension;
+    const allowResolution = !isEdit && !isExtension;
+
+    if (allowDuration && options.duration != null) {
       body.duration = options.duration;
     }
 
-    if (!isEdit && options.aspectRatio != null) {
+    if (allowAspectRatio && options.aspectRatio != null) {
       body.aspect_ratio = options.aspectRatio;
     }
 
-    if (!isEdit && xaiOptions?.resolution != null) {
+    if (allowResolution && xaiOptions?.resolution != null) {
       body.resolution = xaiOptions.resolution;
-    } else if (!isEdit && options.resolution != null) {
+    } else if (allowResolution && options.resolution != null) {
       const mapped = RESOLUTION_MAP[options.resolution];
       if (mapped != null) {
         body.resolution = mapped;
@@ -147,12 +197,17 @@ export class XaiVideoModel implements Experimental_VideoModelV3 {
       }
     }
 
-    // Video editing: pass source video URL (nested object like image)
-    if (xaiOptions?.videoUrl != null) {
-      body.video = { url: xaiOptions.videoUrl };
+    // Video editing: pass source video URL (nested object)
+    if (isEdit) {
+      body.video = { url: xaiOptions!.videoUrl };
+    }
+
+    // Video extension: pass source video URL (nested object)
+    if (isExtension) {
+      body.video = { url: xaiOptions!.videoUrl };
     }
 
-    // Image-to-video: convert SDK image to nested image object
+    // Convert SDK image input to the nested xAI request image object
     if (options.image != null) {
       if (options.image.type === 'url') {
         body.image = { url: options.image.url };
@@ -167,14 +222,23 @@ export class XaiVideoModel implements Experimental_VideoModelV3 {
       }
     }
 
+    // Reference images for R2V (reference-to-video) generation
+    if (hasReferenceImages) {
+      body.reference_images = xaiOptions!.referenceImageUrls!.map(url => ({
+        url,
+      }));
+    }
+
     if (xaiOptions != null) {
       for (const [key, value] of Object.entries(xaiOptions)) {
         if (
           ![
+            'mode',
             'pollIntervalMs',
             'pollTimeoutMs',
             'resolution',
             'videoUrl',
+            'referenceImageUrls',
           ].includes(key)
         ) {
           body[key] = value;
@@ -184,9 +248,19 @@ export class XaiVideoModel implements Experimental_VideoModelV3 {
 
     const baseURL = this.config.baseURL ?? 'https://api.x.ai/v1';
 
-    // Step 1: Create video generation/edit request
+    // Determine endpoint based on mode
+    let endpoint: string;
+    if (isEdit) {
+      endpoint = `${baseURL}/videos/edits`;
+    } else if (isExtension) {
+      endpoint = `${baseURL}/videos/extensions`;
+    } else {
+      endpoint = `${baseURL}/videos/generations`;
+    }
+
+    // Step 1: Create video generation/edit/extension request
     const { value: createResponse } = await postJsonToApi({
-      url: `${baseURL}/videos/${isEdit ? 'edits' : 'generations'}`,
+      url: endpoint,
       headers: combineHeaders(this.config.headers(), options.headers),
       body,
       failedResponseHandler: xaiFailedResponseHandler,
@@ -239,6 +313,14 @@ export class XaiVideoModel implements Experimental_VideoModelV3 {
         statusResponse.status === 'done' ||
         (statusResponse.status == null && statusResponse.video?.url)
       ) {
+        if (statusResponse.video?.respect_moderation === false) {
+          throw new AISDKError({
+            name: 'XAI_VIDEO_MODERATION_ERROR',
+            message:
+              'Video generation was blocked due to a content policy violation.',
+          });
+        }
+
         if (!statusResponse.video?.url) {
           throw new AISDKError({
             name: 'XAI_VIDEO_GENERATION_ERROR',
@@ -268,6 +350,12 @@ export class XaiVideoModel implements Experimental_VideoModelV3 {
               ...(statusResponse.video.duration != null
                 ? { duration: statusResponse.video.duration }
                 : {}),
+              ...(statusResponse.usage?.cost_in_usd_ticks != null
+                ? { costInUsdTicks: statusResponse.usage.cost_in_usd_ticks }
+                : {}),
+              ...(statusResponse.progress != null
+                ? { progress: statusResponse.progress }
+                : {}),
             },
           },
         };
@@ -280,6 +368,13 @@ export class XaiVideoModel implements Experimental_VideoModelV3 {
         });
       }
 
+      if (statusResponse.status === 'failed') {
+        throw new AISDKError({
+          name: 'XAI_VIDEO_GENERATION_FAILED',
+          message: 'Video generation failed.',
+        });
+      }
+
       // 'pending' → continue polling
     }
   }
@@ -299,4 +394,16 @@ const xaiVideoStatusResponseSchema = z.object({
     })
     .nullish(),
   model: z.string().nullish(),
+  usage: z
+    .object({
+      cost_in_usd_ticks: z.number().nullish(),
+    })
+    .nullish(),
+  progress: z.number().nullish(),
+  error: z
+    .object({
+      code: z.string().nullish(),
+      message: z.string().nullish(),
+    })
+    .nullish(),
 });

package/src/xai-video-options.ts

@@ -1,23 +1,145 @@
 import { lazySchema, zodSchema } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
-export type XaiVideoModelOptions = {
+const nonEmptyStringSchema = z.string().min(1);
+const resolutionSchema = z.enum(['480p', '720p']);
+const modeSchema = z.enum(['edit-video', 'extend-video', 'reference-to-video']);
+
+export type XaiVideoMode = z.infer<typeof modeSchema>;
+type XaiVideoResolution = z.infer<typeof resolutionSchema>;
+
+interface XaiVideoSharedOptions {
   pollIntervalMs?: number | null;
   pollTimeoutMs?: number | null;
-  resolution?: '480p' | '720p' | null;
-  videoUrl?: string | null;
-  [key: string]: unknown;
+  resolution?: XaiVideoResolution | null;
+}
+
+interface XaiVideoEditModeOptions extends XaiVideoSharedOptions {
+  /**
+   * Select edit-video mode explicitly for best autocomplete and narrowing.
+   */
+  mode: 'edit-video';
+  /** Source video URL to edit. */
+  videoUrl: string;
+}
+
+interface XaiVideoExtendModeOptions extends XaiVideoSharedOptions {
+  /**
+   * Select extend-video mode explicitly for best autocomplete and narrowing.
+   */
+  mode: 'extend-video';
+  /** Source video URL to extend from its last frame. */
+  videoUrl: string;
+}
+
+interface XaiVideoReferenceToVideoOptions extends XaiVideoSharedOptions {
+  /**
+   * Select reference-to-video mode explicitly for best autocomplete and narrowing.
+   */
+  mode: 'reference-to-video';
+  /** Reference image URLs (1-7) for R2V generation. */
+  referenceImageUrls: string[];
+}
+
+interface XaiVideoGenerationOptions extends XaiVideoSharedOptions {
+  mode?: undefined;
+  videoUrl?: undefined;
+  referenceImageUrls?: undefined;
+}
+
+interface XaiLegacyEditVideoOptions extends XaiVideoSharedOptions {
+  /**
+   * Legacy backward-compatible shape: omitting `mode` while providing
+   * `videoUrl` behaves like edit-video.
+   */
+  mode?: undefined;
+  videoUrl: string;
+}
+
+interface XaiLegacyReferenceToVideoOptions extends XaiVideoSharedOptions {
+  /**
+   * Legacy backward-compatible shape: omitting `mode` while providing
+   * `referenceImageUrls` behaves like reference-to-video.
+   */
+  mode?: undefined;
+  referenceImageUrls: string[];
+}
+
+/**
+ * Provider options for xAI video generation.
+ *
+ * Use the `mode` option to select the operation:
+ *
+ * - `'edit-video'`         + `videoUrl`           -- video editing   (`POST /v1/videos/edits`)
+ * - `'extend-video'`       + `videoUrl`           -- video extension (`POST /v1/videos/extensions`)
+ * - `'reference-to-video'` + `referenceImageUrls` -- R2V generation  (`POST /v1/videos/generations`)
+ * - no `mode`                                     -- standard generation from text prompts or image input
+ *
+ * Runtime remains backward compatible with legacy auto-detected provider
+ * options, but the public TypeScript type is intentionally explicit so editors
+ * can suggest valid modes and flag invalid field combinations.
+ */
+export type XaiVideoModelOptions =
+  | XaiVideoGenerationOptions
+  | XaiVideoEditModeOptions
+  | XaiVideoExtendModeOptions
+  | XaiVideoReferenceToVideoOptions
+  | XaiLegacyEditVideoOptions
+  | XaiLegacyReferenceToVideoOptions;
+
+// ── Runtime schemas ───────────────────────────────────────────────────
+const baseFields = {
+  pollIntervalMs: z.number().positive().nullish(),
+  pollTimeoutMs: z.number().positive().nullish(),
+  resolution: resolutionSchema.nullish(),
 };
 
+const editVideoSchema = z.object({
+  ...baseFields,
+  mode: z.literal('edit-video'),
+  videoUrl: nonEmptyStringSchema,
+  referenceImageUrls: z.undefined().optional(),
+});
+
+const extendVideoSchema = z.object({
+  ...baseFields,
+  mode: z.literal('extend-video'),
+  videoUrl: nonEmptyStringSchema,
+  referenceImageUrls: z.undefined().optional(),
+});
+
+const referenceToVideoSchema = z.object({
+  ...baseFields,
+  mode: z.literal('reference-to-video'),
+  referenceImageUrls: z.array(nonEmptyStringSchema).min(1).max(7),
+  videoUrl: z.undefined().optional(),
+});
+
+const autoDetectSchema = z.object({
+  ...baseFields,
+  mode: z.undefined().optional(),
+  videoUrl: nonEmptyStringSchema.optional(),
+  referenceImageUrls: z.array(nonEmptyStringSchema).min(1).max(7).optional(),
+});
+
+export const xaiVideoModelOptions = z.union([
+  editVideoSchema,
+  extendVideoSchema,
+  referenceToVideoSchema,
+  autoDetectSchema,
+]);
+
+const runtimeSchema = z
+  .object({
+    mode: modeSchema.optional(),
+    videoUrl: nonEmptyStringSchema.optional(),
+    referenceImageUrls: z.array(nonEmptyStringSchema).min(1).max(7).optional(),
+    ...baseFields,
+  })
+  .passthrough();
+
+export type XaiParsedVideoModelOptions = z.infer<typeof runtimeSchema>;
+
 export const xaiVideoModelOptionsSchema = lazySchema(() =>
-  zodSchema(
-    z
-      .object({
-        pollIntervalMs: z.number().positive().nullish(),
-        pollTimeoutMs: z.number().positive().nullish(),
-        resolution: z.enum(['480p', '720p']).nullish(),
-        videoUrl: z.string().nullish(),
-      })
-      .passthrough(),
-  ),
+  zodSchema(runtimeSchema),
 );