@ai-sdk/xai 3.0.56 → 3.0.57

package/docs/01-xai.mdx

@@ -876,3 +876,181 @@ const { images } = await generateImage({
 | -------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------- |
 | `grok-2-image`       | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `2:1`, `1:2`, `19.5:9`, `9:19.5`, `20:9`, `9:20`, `auto` | <Check size={18} /> |
 | `grok-imagine-image` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `2:1`, `1:2`, `19.5:9`, `9:19.5`, `20:9`, `9:20`, `auto` | <Check size={18} /> |
+
+## Video Models
+
+You can create xAI video models using the `.video()` factory method.
+For more on video generation with the AI SDK see [generateVideo()](/docs/reference/ai-sdk-core/generate-video).
+
+This provider supports three video generation modes: text-to-video, image-to-video, and video editing.
+
+### Text-to-Video
+
+Generate videos from text prompts:
+
+```ts
+import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
+import { experimental_generateVideo as generateVideo } from 'ai';
+
+const { videos } = await generateVideo({
+  model: xai.video('grok-imagine-video'),
+  prompt: 'A chicken flying into the sunset in the style of 90s anime.',
+  aspectRatio: '16:9',
+  duration: 5,
+  providerOptions: {
+    xai: {
+      pollTimeoutMs: 600000, // 10 minutes
+    } satisfies XaiVideoModelOptions,
+  },
+});
+```
+
+### Image-to-Video
+
+Generate videos using an image as the starting frame with an optional text prompt:
+
+```ts
+import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
+import { experimental_generateVideo as generateVideo } from 'ai';
+
+const { videos } = await generateVideo({
+  model: xai.video('grok-imagine-video'),
+  prompt: {
+    image: 'https://example.com/start-frame.png',
+    text: 'The cat slowly turns its head and blinks',
+  },
+  duration: 5,
+  providerOptions: {
+    xai: {
+      pollTimeoutMs: 600000, // 10 minutes
+    } satisfies XaiVideoModelOptions,
+  },
+});
+```
+
+### Video Editing
+
+Edit an existing video using a text prompt by providing a source video URL via provider options:
+
+```ts
+import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
+import { experimental_generateVideo as generateVideo } from 'ai';
+
+const { videos } = await generateVideo({
+  model: xai.video('grok-imagine-video'),
+  prompt: 'Give the person sunglasses and a hat',
+  providerOptions: {
+    xai: {
+      videoUrl: 'https://example.com/source-video.mp4',
+      pollTimeoutMs: 600000, // 10 minutes
+    } satisfies XaiVideoModelOptions,
+  },
+});
+```
+
+<Note>
+  Video editing accepts input videos up to 8.7 seconds long. The `duration`,
+  `aspectRatio`, and `resolution` parameters are not supported for editing - the
+  output matches the input video's properties (capped at 720p).
+</Note>
+
+### Chaining and Concurrent Edits
+
+The xAI-hosted video URL is available in `providerMetadata.xai.videoUrl`.
+You can use it to chain sequential edits or branch into concurrent edits
+using `Promise.all`:
+
+```ts
+import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
+import { experimental_generateVideo as generateVideo } from 'ai';
+
+const providerOptions = {
+  xai: {
+    videoUrl: 'https://example.com/source-video.mp4',
+    pollTimeoutMs: 600000,
+  } satisfies XaiVideoModelOptions,
+};
+
+// Step 1: Apply an initial edit
+const step1 = await generateVideo({
+  model: xai.video('grok-imagine-video'),
+  prompt: 'Add a party hat to the person',
+  providerOptions,
+});
+
+// Get the xAI-hosted URL from provider metadata
+const step1VideoUrl = step1.providerMetadata?.xai?.videoUrl as string;
+
+// Step 2: Apply two more edits concurrently, building on step 1
+const [withSunglasses, withScarf] = await Promise.all([
+  generateVideo({
+    model: xai.video('grok-imagine-video'),
+    prompt: 'Add sunglasses',
+    providerOptions: {
+      xai: { videoUrl: step1VideoUrl, pollTimeoutMs: 600000 },
+    },
+  }),
+  generateVideo({
+    model: xai.video('grok-imagine-video'),
+    prompt: 'Add a scarf',
+    providerOptions: {
+      xai: { videoUrl: step1VideoUrl, pollTimeoutMs: 600000 },
+    },
+  }),
+]);
+```
+
+### Video Provider Options
+
+The following provider options are available via `providerOptions.xai`.
+You can validate the provider options using the `XaiVideoModelOptions` type.
+
+- **pollIntervalMs** _number_
+
+  Polling interval in milliseconds for checking task status. Defaults to 5000.
+
+- **pollTimeoutMs** _number_
+
+  Maximum wait time in milliseconds for video generation. Defaults to 600000 (10 minutes).
+
+- **resolution** _'480p' | '720p'_
+
+  Video resolution. When using the SDK's standard `resolution` parameter,
+  `1280x720` maps to `720p` and `854x480` maps to `480p`.
+  Use this provider option to pass the native format directly.
+
+- **videoUrl** _string_
+
+  URL of a source video for video editing. When provided, the prompt is used
+  to describe the desired edits to the video.
+
+<Note>
+  Video generation is an asynchronous process that can take several minutes.
+  Consider setting `pollTimeoutMs` to at least 10 minutes (600000ms) for
+  reliable operation. Generated video URLs are ephemeral and should be
+  downloaded promptly.
+</Note>
+
+### Aspect Ratio and Resolution
+
+For **text-to-video**, you can specify both `aspectRatio` and `resolution`.
+The default aspect ratio is `16:9` and the default resolution is `480p`.
+
+For **image-to-video**, the output defaults to the input image's aspect ratio.
+If you specify `aspectRatio`, it will override this and stretch the image to the
+desired ratio.
+
+For **video editing**, the output matches the input video's aspect ratio and
+resolution. Custom `duration`, `aspectRatio`, and `resolution` are not
+supported - the output resolution is capped at 720p (e.g., a 1080p input
+will be downsized to 720p).
+
+### Video Model Capabilities
+
+| Model                | Duration | Aspect Ratios                                     | Resolution     | Image-to-Video      | Video Editing       |
+| -------------------- | -------- | ------------------------------------------------- | -------------- | ------------------- | ------------------- |
+| `grok-imagine-video` | 1–15s    | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3` | `480p`, `720p` | <Check size={18} /> | <Check size={18} /> |
+
+<Note>
+  You can also pass any available provider model ID as a string if needed.
+</Note>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/xai",
-  "version": "3.0.56",
+  "version": "3.0.57",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -29,8 +29,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/openai-compatible": "2.0.30",
     "@ai-sdk/provider-utils": "4.0.15",
+    "@ai-sdk/openai-compatible": "2.0.30",
     "@ai-sdk/provider": "3.0.8"
   },
   "devDependencies": {

package/src/index.ts

@@ -14,6 +14,12 @@ export type {
   /** @deprecated Use `XaiImageModelOptions` instead. */
   XaiImageModelOptions as XaiImageProviderOptions,
 } from './xai-image-options';
+export type { XaiVideoModelId } from './xai-video-settings';
+export type {
+  XaiVideoModelOptions,
+  /** @deprecated Use `XaiVideoModelOptions` instead. */
+  XaiVideoModelOptions as XaiVideoProviderOptions,
+} from './xai-video-options';
 export { createXai, xai } from './xai-provider';
 export type { XaiProvider, XaiProviderSettings } from './xai-provider';
 export {

package/src/xai-provider.ts

@@ -1,4 +1,5 @@
 import {
+  type Experimental_VideoModelV3,
   ImageModelV3,
   LanguageModelV3,
   NoSuchModelError,
@@ -19,6 +20,8 @@ import { XaiResponsesLanguageModel } from './responses/xai-responses-language-mo
 import { XaiResponsesModelId } from './responses/xai-responses-options';
 import { xaiTools } from './tool';
 import { VERSION } from './version';
+import { XaiVideoModel } from './xai-video-model';
+import { XaiVideoModelId } from './xai-video-settings';
 
 export interface XaiProvider extends ProviderV3 {
   /**
@@ -51,6 +54,16 @@ export interface XaiProvider extends ProviderV3 {
    */
   imageModel(modelId: XaiImageModelId): ImageModelV3;
 
+  /**
+   * Creates an Xai video model for video generation.
+   */
+  video(modelId: XaiVideoModelId): Experimental_VideoModelV3;
+
+  /**
+   * Creates an Xai video model for video generation.
+   */
+  videoModel(modelId: XaiVideoModelId): Experimental_VideoModelV3;
+
   /**
    * Server-side agentic tools for use with the responses API.
    */
@@ -131,6 +144,15 @@ export function createXai(options: XaiProviderSettings = {}): XaiProvider {
     });
   };
 
+  const createVideoModel = (modelId: XaiVideoModelId) => {
+    return new XaiVideoModel(modelId, {
+      provider: 'xai.video',
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+  };
+
   const provider = (modelId: XaiChatModelId) =>
     createChatLanguageModel(modelId);
 
@@ -144,6 +166,8 @@ export function createXai(options: XaiProviderSettings = {}): XaiProvider {
   provider.textEmbeddingModel = provider.embeddingModel;
   provider.imageModel = createImageModel;
   provider.image = createImageModel;
+  provider.videoModel = createVideoModel;
+  provider.video = createVideoModel;
   provider.tools = xaiTools;
 
   return provider;

package/src/xai-video-model.ts

@@ -0,0 +1,302 @@
+import {
+  AISDKError,
+  type Experimental_VideoModelV3,
+  type SharedV3Warning,
+} from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  convertUint8ArrayToBase64,
+  createJsonResponseHandler,
+  delay,
+  type FetchFunction,
+  getFromApi,
+  parseProviderOptions,
+  postJsonToApi,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { xaiFailedResponseHandler } from './xai-error';
+import {
+  type XaiVideoModelOptions,
+  xaiVideoModelOptionsSchema,
+} from './xai-video-options';
+import type { XaiVideoModelId } from './xai-video-settings';
+
+interface XaiVideoModelConfig {
+  provider: string;
+  baseURL: string | undefined;
+  headers: () => Record<string, string | undefined>;
+  fetch?: FetchFunction;
+  _internal?: {
+    currentDate?: () => Date;
+  };
+}
+
+const RESOLUTION_MAP: Record<string, string> = {
+  '1280x720': '720p',
+  '854x480': '480p',
+  '640x480': '480p',
+};
+
+export class XaiVideoModel implements Experimental_VideoModelV3 {
+  readonly specificationVersion = 'v3';
+  readonly maxVideosPerCall = 1;
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(
+    readonly modelId: XaiVideoModelId,
+    private config: XaiVideoModelConfig,
+  ) {}
+
+  async doGenerate(
+    options: Parameters<Experimental_VideoModelV3['doGenerate']>[0],
+  ): Promise<Awaited<ReturnType<Experimental_VideoModelV3['doGenerate']>>> {
+    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
+    const warnings: SharedV3Warning[] = [];
+
+    const xaiOptions = (await parseProviderOptions({
+      provider: 'xai',
+      providerOptions: options.providerOptions,
+      schema: xaiVideoModelOptionsSchema,
+    })) as XaiVideoModelOptions | undefined;
+
+    const isEdit = xaiOptions?.videoUrl != null;
+
+    if (options.fps != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'fps',
+        details: 'xAI video models do not support custom FPS.',
+      });
+    }
+
+    if (options.seed != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'seed',
+        details: 'xAI video models do not support seed.',
+      });
+    }
+
+    if (options.n != null && options.n > 1) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'n',
+        details:
+          'xAI video models do not support generating multiple videos per call. ' +
+          'Only 1 video will be generated.',
+      });
+    }
+
+    if (isEdit && options.duration != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'duration',
+        details: 'xAI video editing does not support custom duration.',
+      });
+    }
+
+    if (isEdit && options.aspectRatio != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'aspectRatio',
+        details: 'xAI video editing does not support custom aspect ratio.',
+      });
+    }
+
+    if (
+      isEdit &&
+      (xaiOptions?.resolution != null || options.resolution != null)
+    ) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'resolution',
+        details: 'xAI video editing does not support custom resolution.',
+      });
+    }
+
+    const body: Record<string, unknown> = {
+      model: this.modelId,
+      prompt: options.prompt,
+    };
+
+    if (!isEdit && options.duration != null) {
+      body.duration = options.duration;
+    }
+
+    if (!isEdit && options.aspectRatio != null) {
+      body.aspect_ratio = options.aspectRatio;
+    }
+
+    if (!isEdit && xaiOptions?.resolution != null) {
+      body.resolution = xaiOptions.resolution;
+    } else if (!isEdit && options.resolution != null) {
+      const mapped = RESOLUTION_MAP[options.resolution];
+      if (mapped != null) {
+        body.resolution = mapped;
+      } else {
+        warnings.push({
+          type: 'unsupported',
+          feature: 'resolution',
+          details:
+            `Unrecognized resolution "${options.resolution}". ` +
+            'Use providerOptions.xai.resolution with "480p" or "720p" instead.',
+        });
+      }
+    }
+
+    // Video editing: pass source video URL (nested object like image)
+    if (xaiOptions?.videoUrl != null) {
+      body.video = { url: xaiOptions.videoUrl };
+    }
+
+    // Image-to-video: convert SDK image to nested image object
+    if (options.image != null) {
+      if (options.image.type === 'url') {
+        body.image = { url: options.image.url };
+      } else {
+        const base64Data =
+          typeof options.image.data === 'string'
+            ? options.image.data
+            : convertUint8ArrayToBase64(options.image.data);
+        body.image = {
+          url: `data:${options.image.mediaType};base64,${base64Data}`,
+        };
+      }
+    }
+
+    if (xaiOptions != null) {
+      for (const [key, value] of Object.entries(xaiOptions)) {
+        if (
+          ![
+            'pollIntervalMs',
+            'pollTimeoutMs',
+            'resolution',
+            'videoUrl',
+          ].includes(key)
+        ) {
+          body[key] = value;
+        }
+      }
+    }
+
+    const baseURL = this.config.baseURL ?? 'https://api.x.ai/v1';
+
+    // Step 1: Create video generation/edit request
+    const { value: createResponse } = await postJsonToApi({
+      url: `${baseURL}/videos/${isEdit ? 'edits' : 'generations'}`,
+      headers: combineHeaders(this.config.headers(), options.headers),
+      body,
+      failedResponseHandler: xaiFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(
+        xaiCreateVideoResponseSchema,
+      ),
+      abortSignal: options.abortSignal,
+      fetch: this.config.fetch,
+    });
+
+    const requestId = createResponse.request_id;
+    if (!requestId) {
+      throw new AISDKError({
+        name: 'XAI_VIDEO_GENERATION_ERROR',
+        message: `No request_id returned from xAI API. Response: ${JSON.stringify(createResponse)}`,
+      });
+    }
+
+    // Step 2: Poll for completion
+    const pollIntervalMs = xaiOptions?.pollIntervalMs ?? 5000;
+    const pollTimeoutMs = xaiOptions?.pollTimeoutMs ?? 600000;
+    const startTime = Date.now();
+    let responseHeaders: Record<string, string> | undefined;
+
+    while (true) {
+      await delay(pollIntervalMs, { abortSignal: options.abortSignal });
+
+      if (Date.now() - startTime > pollTimeoutMs) {
+        throw new AISDKError({
+          name: 'XAI_VIDEO_GENERATION_TIMEOUT',
+          message: `Video generation timed out after ${pollTimeoutMs}ms`,
+        });
+      }
+
+      const { value: statusResponse, responseHeaders: pollHeaders } =
+        await getFromApi({
+          url: `${baseURL}/videos/${requestId}`,
+          headers: combineHeaders(this.config.headers(), options.headers),
+          successfulResponseHandler: createJsonResponseHandler(
+            xaiVideoStatusResponseSchema,
+          ),
+          failedResponseHandler: xaiFailedResponseHandler,
+          abortSignal: options.abortSignal,
+          fetch: this.config.fetch,
+        });
+
+      responseHeaders = pollHeaders;
+
+      if (
+        statusResponse.status === 'done' ||
+        (statusResponse.status == null && statusResponse.video?.url)
+      ) {
+        if (!statusResponse.video?.url) {
+          throw new AISDKError({
+            name: 'XAI_VIDEO_GENERATION_ERROR',
+            message:
+              'Video generation completed but no video URL was returned.',
+          });
+        }
+
+        return {
+          videos: [
+            {
+              type: 'url' as const,
+              url: statusResponse.video.url,
+              mediaType: 'video/mp4',
+            },
+          ],
+          warnings,
+          response: {
+            timestamp: currentDate,
+            modelId: this.modelId,
+            headers: responseHeaders,
+          },
+          providerMetadata: {
+            xai: {
+              requestId,
+              videoUrl: statusResponse.video.url,
+              ...(statusResponse.video.duration != null
+                ? { duration: statusResponse.video.duration }
+                : {}),
+            },
+          },
+        };
+      }
+
+      if (statusResponse.status === 'expired') {
+        throw new AISDKError({
+          name: 'XAI_VIDEO_GENERATION_EXPIRED',
+          message: 'Video generation request expired.',
+        });
+      }
+
+      // 'pending' → continue polling
+    }
+  }
+}
+
+const xaiCreateVideoResponseSchema = z.object({
+  request_id: z.string().nullish(),
+});
+
+const xaiVideoStatusResponseSchema = z.object({
+  status: z.string().nullish(),
+  video: z
+    .object({
+      url: z.string(),
+      duration: z.number().nullish(),
+      respect_moderation: z.boolean().nullish(),
+    })
+    .nullish(),
+  model: z.string().nullish(),
+});

package/src/xai-video-options.ts

@@ -0,0 +1,23 @@
+import { lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export type XaiVideoModelOptions = {
+  pollIntervalMs?: number | null;
+  pollTimeoutMs?: number | null;
+  resolution?: '480p' | '720p' | null;
+  videoUrl?: string | null;
+  [key: string]: unknown;
+};
+
+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(),
+  ),
+);

package/src/xai-video-settings.ts

@@ -0,0 +1 @@
+export type XaiVideoModelId = 'grok-imagine-video' | (string & {});