@ai-sdk/xai 4.0.0-beta.21 → 4.0.0-beta.24

package/src/xai-provider.ts

@@ -1,5 +1,6 @@
 import {
   type Experimental_VideoModelV4,
+  FilesV4,
   ImageModelV4,
   LanguageModelV4,
   NoSuchModelError,
@@ -20,6 +21,7 @@ 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';
 
@@ -61,6 +63,11 @@ export interface XaiProvider extends ProviderV4 {
    */
   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.
    */
@@ -150,6 +157,14 @@ export function createXai(options: XaiProviderSettings = {}): XaiProvider {
     });
   };
 
+  const createFiles = () =>
+    new XaiFiles({
+      provider: 'xai.files',
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
   const provider = (modelId: XaiResponsesModelId) =>
     createResponsesLanguageModel(modelId);
 
@@ -165,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

@@ -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,6 +37,27 @@ const RESOLUTION_MAP: Record<string, string> = {
   '640x480': '480p',
 };
 
+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;
@@ -60,9 +81,13 @@ export class XaiVideoModel implements Experimental_VideoModelV4 {
       provider: 'xai',
       providerOptions: options.providerOptions,
       schema: xaiVideoModelOptionsSchema,
-    })) as XaiVideoModelOptions | undefined;
+    })) as XaiParsedVideoModelOptions | undefined;
 
-    const isEdit = xaiOptions?.videoUrl != null;
+    const effectiveMode = resolveVideoMode(xaiOptions);
+
+    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_VideoModelV4 {
       });
     }
 
+    // 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_VideoModelV4 {
       });
     }
 
+    // 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_VideoModelV4 {
       }
     }
 
-    // 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 };
     }
 
-    // Image-to-video: convert SDK image to nested image object
+    // Video extension: pass source video URL (nested object)
+    if (isExtension) {
+      body.video = { url: xaiOptions!.videoUrl };
+    }
+
+    // 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_VideoModelV4 {
       }
     }
 
+    // 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_VideoModelV4 {
 
     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,
@@ -279,6 +353,9 @@ export class XaiVideoModel implements Experimental_VideoModelV4 {
               ...(statusResponse.usage?.cost_in_usd_ticks != null
                 ? { costInUsdTicks: statusResponse.usage.cost_in_usd_ticks }
                 : {}),
+              ...(statusResponse.progress != null
+                ? { progress: statusResponse.progress }
+                : {}),
             },
           },
         };
@@ -291,6 +368,13 @@ export class XaiVideoModel implements Experimental_VideoModelV4 {
         });
       }
 
+      if (statusResponse.status === 'failed') {
+        throw new AISDKError({
+          name: 'XAI_VIDEO_GENERATION_FAILED',
+          message: 'Video generation failed.',
+        });
+      }
+
       // 'pending' → continue polling
     }
   }
@@ -315,4 +399,11 @@ const xaiVideoStatusResponseSchema = 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),
 );