Backport: feat(provider/xai): add video extension and reference-to-video (R2V) support (#14079)

This is an automated backport of #13887 to the release-v6.0 branch. FYI
@Jaaneek
~~This backport has conflicts that need to be resolved manually.~~
Conflicts resolved.

### `git cherry-pick` output

```
Auto-merging content/providers/01-ai-sdk-providers/01-xai.mdx
Auto-merging packages/xai/src/xai-video-model.test.ts
Auto-merging packages/xai/src/xai-video-model.ts
CONFLICT (content): Merge conflict in packages/xai/src/xai-video-model.ts
error: could not apply f51c95e... feat(provider/xai): add video extension and reference-to-video (R2V) support (#13887)
hint: After resolving the conflicts, mark them with
hint: "git add/rm <pathspec>", then run
hint: "git cherry-pick --continue".
hint: You can instead skip this commit with "git cherry-pick --skip".
hint: To abort and get back to the state before "git cherry-pick",
hint: run "git cherry-pick --abort".
hint: Disable this message with "git config set advice.mergeConflict false"
```

---------

Co-authored-by: Jaaneek <25470423+Jaaneek@users.noreply.github.com>
Co-authored-by: Felix Arntz <felix.arntz@vercel.com>

Author: 3 people

.changeset/tidy-pumpkins-rest.md

@@ -0,0 +1,5 @@
+---
+"@ai-sdk/xai": patch
+---
+
+feat(provider/xai): add video extension and reference-to-video (R2V) support

content/docs/03-ai-sdk-core/38-video-generation.mdx

@@ -361,6 +361,6 @@ try {
 | [Kling AI](/providers/ai-sdk-providers/klingai#video-models)            | `kling-v2.6-i2v`            | Image-to-video                         |
 | [Kling AI](/providers/ai-sdk-providers/klingai#video-models)            | `kling-v2.6-motion-control` | Motion control                         |
 | [Replicate](/providers/ai-sdk-providers/replicate#video-models)         | `minimax/video-01`          | Text-to-video                          |
-| [xAI](/providers/ai-sdk-providers/xai#video-models)                     | `grok-imagine-video`        | Text-to-video, image-to-video, editing |
+| [xAI](/providers/ai-sdk-providers/xai#video-models)                     | `grok-imagine-video`        | Text-to-video, image-to-video, editing, extension, R2V |
 
 Above are a small subset of the video models supported by the AI SDK providers. For more, see the respective provider documentation.

content/providers/01-ai-sdk-providers/01-xai.mdx

@@ -5,7 +5,7 @@ import { run } from '../../lib/run';
 import { withSpinner } from '../../lib/spinner';
 
 run(async () => {
-  const { videos } = await withSpinner(
+  const { video } = await withSpinner(
     'Generating xAI video with grok-imagine-video...',
     () =>
       generateVideo({
@@ -21,5 +21,5 @@ run(async () => {
       }),
   );
 
-  await presentVideos(videos);
+  await presentVideos([video]);
 });

examples/ai-functions/src/generate-video/xai/basic.ts

@@ -12,6 +12,7 @@ run(async () => {
       prompt: 'Make the cat look like a princess with a small tiara',
       providerOptions: {
         xai: {
+          mode: 'edit-video',
           videoUrl:
             'https://raw.githubusercontent.com/vercel/ai/refs/heads/main/examples/ai-functions/data/prudence.mp4',
           pollTimeoutMs: 600000,
@@ -24,7 +25,12 @@ run(async () => {
   await presentVideos(step1.videos);
 
   // Use the xAI-hosted URL from step 1 as input for the next two edits
-  const step1VideoUrl = step1.providerMetadata?.xai?.videoUrl as string;
+  const step1VideoUrl = step1.providerMetadata?.xai?.videoUrl as
+    | string
+    | undefined;
+  if (step1VideoUrl == null) {
+    throw new Error('xAI provider metadata did not include a step-1 videoUrl.');
+  }
 
   // Step 2: Apply two more edits concurrently, building on step 1
   const edits = [
@@ -42,6 +48,7 @@ run(async () => {
             prompt,
             providerOptions: {
               xai: {
+                mode: 'edit-video',
                 videoUrl: step1VideoUrl,
                 pollTimeoutMs: 600000,
               } satisfies XaiVideoModelOptions,

examples/ai-functions/src/generate-video/xai/edit-concurrent.ts

@@ -5,14 +5,15 @@ import { run } from '../../lib/run';
 import { withSpinner } from '../../lib/spinner';
 
 run(async () => {
-  const { videos } = await withSpinner(
+  const { video } = await withSpinner(
     'Editing video with xAI grok-imagine-video...',
     () =>
       generateVideo({
         model: xai.video('grok-imagine-video'),
         prompt: 'Render this cat as a dog in the style of 90s anime.',
         providerOptions: {
           xai: {
+            mode: 'edit-video',
             videoUrl:
               'https://raw.githubusercontent.com/vercel/ai/refs/heads/main/examples/ai-functions/data/prudence.mp4',
             pollTimeoutMs: 600000, // 10 minutes
@@ -21,5 +22,5 @@ run(async () => {
       }),
   );
 
-  await presentVideos(videos);
+  await presentVideos([video]);
 });

examples/ai-functions/src/generate-video/xai/edit.ts

@@ -0,0 +1,45 @@
+import { type XaiVideoModelOptions, xai } from '@ai-sdk/xai';
+import { experimental_generateVideo as generateVideo } from 'ai';
+import { run } from '../../lib/run';
+
+// Demonstrates that aspectRatio and resolution are silently ignored
+// (with a warning) when using extension mode.
+run(async () => {
+  console.log('Step 1: generating a source video...');
+  const source = await generateVideo({
+    model: xai.video('grok-imagine-video'),
+    prompt: 'A cat sitting on a windowsill.',
+    duration: 3,
+    providerOptions: {
+      xai: { pollTimeoutMs: 600000 } satisfies XaiVideoModelOptions,
+    },
+  });
+
+  const sourceUrl = source.providerMetadata?.xai?.videoUrl as
+    | string
+    | undefined;
+  if (sourceUrl == null) {
+    throw new Error('xAI provider metadata did not include a source videoUrl.');
+  }
+
+  console.log('Source video URL:', sourceUrl);
+
+  console.log('\nStep 2: extending with unsupported params...');
+  const result = await generateVideo({
+    model: xai.video('grok-imagine-video'),
+    prompt: 'The cat stretches and jumps off the windowsill.',
+    duration: 5,
+    aspectRatio: '16:9',
+    resolution: '1280x720',
+    providerOptions: {
+      xai: {
+        mode: 'extend-video',
+        videoUrl: sourceUrl,
+        pollTimeoutMs: 600000,
+      } satisfies XaiVideoModelOptions,
+    },
+  });
+
+  console.log('\nWarnings (aspectRatio and resolution are unsupported):');
+  console.log(JSON.stringify(result.warnings, null, 2));
+});

examples/ai-functions/src/generate-video/xai/extend-warnings.ts

@@ -0,0 +1,60 @@
+import { type XaiVideoModelOptions, xai } from '@ai-sdk/xai';
+import { experimental_generateVideo as generateVideo } from 'ai';
+import { presentVideos } from '../../lib/present-video';
+import { run } from '../../lib/run';
+import { withSpinner } from '../../lib/spinner';
+
+// Video extension: continue an existing video from its last frame.
+// The `duration` controls the length of the *extension* only, not the total.
+// `aspectRatio` and `resolution` are not supported in extension mode — the
+// output inherits those from the input video.
+run(async () => {
+  // Step 1: Generate a short source video.
+  const source = await withSpinner('Step 1: Generating source video...', () =>
+    generateVideo({
+      model: xai.video('grok-imagine-video'),
+      prompt: 'A cat sitting on a sunlit windowsill, tail gently swishing.',
+      duration: 5,
+      aspectRatio: '16:9',
+      providerOptions: {
+        xai: { pollTimeoutMs: 600000 } satisfies XaiVideoModelOptions,
+      },
+    }),
+  );
+
+  const sourceUrl = source.providerMetadata?.xai?.videoUrl as
+    | string
+    | undefined;
+  if (sourceUrl == null) {
+    throw new Error('xAI provider metadata did not include a source videoUrl.');
+  }
+
+  console.log('Source video URL:', sourceUrl);
+  await presentVideos(source.videos);
+
+  // Step 2: Extend the video with a new scene.
+  const extended = await withSpinner(
+    'Step 2: Extending video with a new scene...',
+    () =>
+      generateVideo({
+        model: xai.video('grok-imagine-video'),
+        prompt:
+          'The cat slowly turns its head, notices a butterfly, and leaps off the windowsill.',
+        duration: 6,
+        providerOptions: {
+          xai: {
+            mode: 'extend-video',
+            videoUrl: sourceUrl,
+            pollTimeoutMs: 600000,
+          } satisfies XaiVideoModelOptions,
+        },
+      }),
+  );
+
+  console.log('\nExtended video (original 5s + 6s extension = 11s total):');
+  console.log(
+    'Provider metadata:',
+    JSON.stringify(extended.providerMetadata, null, 2),
+  );
+  await presentVideos(extended.videos);
+});

examples/ai-functions/src/generate-video/xai/extend.ts

@@ -6,7 +6,7 @@ import { run } from '../../lib/run';
 import { withSpinner } from '../../lib/spinner';
 
 run(async () => {
-  const { videos } = await withSpinner(
+  const { video } = await withSpinner(
     'Generating xAI image-to-video from base64...',
     () =>
       generateVideo({
@@ -24,5 +24,5 @@ run(async () => {
       }),
   );
 
-  await presentVideos(videos);
+  await presentVideos([video]);
 });

examples/ai-functions/src/generate-video/xai/i2v-base64.ts

@@ -5,7 +5,7 @@ import { run } from '../../lib/run';
 import { withSpinner } from '../../lib/spinner';
 
 run(async () => {
-  const { videos } = await withSpinner(
+  const { video } = await withSpinner(
     'Generating xAI image-to-video with grok-imagine-video...',
     () =>
       generateVideo({
@@ -24,5 +24,5 @@ run(async () => {
       }),
   );
 
-  await presentVideos(videos);
+  await presentVideos([video]);
 });