Model Capabilities

Video Generation

Generate videos from text prompts, animate still images, use reference images to guide style and content, edit existing videos, or extend them with natural language. The API supports configurable duration, aspect ratio, and resolution for generated videos — with the SDK handling the asynchronous polling automatically.

Quick Start

Generate a video with a single API call:

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client.video.generate(
    prompt="A glowing crystal-powered rocket launching from the red dunes of Mars, ancient alien ruins lighting up in the background as it soars into a sky full of unfamiliar constellations",
    model="grok-imagine-video",
    duration=10,
    aspect_ratio="16:9",
    resolution="720p",
)

print(response.url)

import os
import time
import requests

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
}

response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    headers=headers,
    json={
        "model": "grok-imagine-video",
        "prompt": "A glowing crystal-powered rocket launching from the red dunes of Mars, ancient alien ruins lighting up in the background as it soars into a sky full of unfamiliar constellations",
        "duration": 10,
        "aspect_ratio": "16:9",
        "resolution": "720p",
    },
)

request_id = response.json()["request_id"]

# Poll until the video is ready
while True:
    result = requests.get(
        f"https://api.x.ai/v1/videos/%3C/span%3E%3Cspan%20style="color:#005CC5;--shiki-dark:#79B8FF">{request_id}",
        headers={"Authorization": headers["Authorization"]},
    )
    data = result.json()
    if data["status"] == "done":
        print(data["video"]["url"])
        break
    elif data["status"] == "expired":
        print("Request expired")
        break
    time.sleep(5)

import { xai } from "@ai-sdk/xai";
import { experimental_generateVideo as generateVideo } from "ai";

const result = await generateVideo({
    model: xai.video("grok-imagine-video"),
    prompt: "A glowing crystal-powered rocket launching from the red dunes of Mars, ancient alien ruins lighting up in the background as it soars into a sky full of unfamiliar constellations",
    duration: 10,
    aspectRatio: "16:9",
    providerOptions: {
        xai: { resolution: "720p" },
    },
});

const videoUrl = result.providerMetadata?.xai?.videoUrl;
console.log(videoUrl);

curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A glowing crystal-powered rocket launching from the red dunes of Mars, ancient alien ruins lighting up in the background as it soars into a sky full of unfamiliar constellations",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

Video generation is an asynchronous process that typically takes up to several minutes to complete. The exact time varies based on:

Prompt complexity — More detailed scenes require additional processing
Duration — Longer videos take more time to generate
Resolution — Higher resolutions (720p vs 480p) increase processing time
Video editing — Editing existing videos adds overhead compared to image-to-video or text-to-video

How it works

Under the hood, video generation is a two-step process:

Start — Submit a generation request and receive a request_id
Poll — Repeatedly check the status using the request_id until the video is ready

The xAI SDK's generate() and extend() methods abstract this entirely — they submit your request, poll for the result, and return the completed video response. You don't need to manage request IDs or implement polling logic. For long-running generations, you can customize the polling behavior with timeout and interval parameters, or handle polling manually for full control over the generation lifecycle.

REST API users must implement this two-step flow manually:

Step 1: Start the generation request

Bash

curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A glowing crystal-powered rocket launching from Mars"
  }'

Response:

JSON

{"request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"}

Step 2: Poll for the result

Use the request_id to check the status. Keep polling every few seconds until the video is ready:

Bash

curl -X GET "https://api.x.ai/v1/videos/%7Brequest_id%7D" \
  -H "Authorization: Bearer $XAI_API_KEY"

The response includes a status field with one of these values:

Status	Description
`pending`	Video is still being generated
`done`	Video is ready
`expired`	Request has expired
`failed`	Video generation failed

Response (when complete):

JSON

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/.../video.mp4",
    "duration": 8,
    "respect_moderation": true
  },
  "model": "grok-imagine-video"
}

Videos are returned as temporary URLs. Access the xAI-hosted URL directly when you need it, or download/process it promptly if you need to keep a copy.

Generate Videos from Images

Transform a still image into a video by providing a source image along with your prompt. The model animates the image content based on your instructions.

You can provide the source image as:

A public URL pointing to an image
A base64-encoded data URI (e.g., data:image/jpeg;base64,...)

The demo below shows this in action — hold to animate a still image:

In the Vercel AI SDK, the prompt parameter accepts an object with image and text fields for image-to-video generation. The image field can be a URL string, base64-encoded string, Uint8Array, ArrayBuffer, or Buffer.

Edit Existing Videos

Edit an existing video by providing a source video along with your prompt. The model understands the video content and applies your requested changes.

The input video must have the .mp4 extension and be encoded with .mp4 supported codecs such as H.265 / H.264 / AV1, etc.
The maximum length of the input video provided via the video_url parameter is 8.7 seconds.
The duration, aspect_ratio, and resolution parameters are not supported for video editing — the output retains the duration and aspect ratio of the input, and matches its resolution (capped at 720p).

The demo below shows video editing in action — grok-imagine-video delivers high-fidelity edits with strong scene preservation, modifying only what you ask for while keeping the rest of the video intact:

In the Vercel AI SDK, video editing is triggered by setting providerOptions.xai.mode to "edit-video" and passing providerOptions.xai.videoUrl with a source video URL. The prompt describes the desired modifications; duration, aspectRatio, and resolution are ignored because the output inherits these properties from the input video, capped at 720p.

Generate Videos using Reference Images

Provide one or more reference images to incorporate specific people, objects, clothing, or other visual elements into the generated video. The model uses the reference images as a visual guide, producing a video that features the content from those images — making it ideal for use cases like virtual try-on, product placement, or character-consistent storytelling.

Unlike image-to-video where the source image becomes the starting frame, reference images influence what appears in the video without locking in the first frame.

Each reference image can be provided as a public HTTPS URL or a base64-encoded data URI. In the AI SDK, set providerOptions.xai.mode to "reference-to-video" and pass the images with providerOptions.xai.referenceImageUrls.

A non-empty prompt is required when using reference images.
A maximum of 7 reference images can be provided per request.
The maximum duration allowed when using reference images is 10 seconds.
Reference images cannot be combined with image-to-video or video editing. Only one mode can be active per request, determined by the parameters on the request.

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client.video.generate(
    prompt="slow zoom in on the white fashion runway stage. then, the model from <IMAGE_1> walks in from the back of the shot from the white opening, and gracefully walk out onto the front of the white stage platform. they wear the shirt from <IMAGE_2> and black flared jeans. they look dramatically at the camera. high quality slow motion shot. fun, playful. skin pores. highly detailed faces. perfect shot. they reach the end of the runway and look at the camera as the camera slowly zooms. subtle smile.",
    model="grok-imagine-video",
    reference_image_urls=[
        "<IMAGE_URL_1>",
        "<IMAGE_URL_2>",
        "<IMAGE_URL_3>",
    ],
    duration=10,
    aspect_ratio="16:9",
    resolution="720p",
)

print(response.url)

import os
import time
import requests

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
}

response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    headers=headers,
    json={
        "model": "grok-imagine-video",
        "prompt": "slow zoom in on the white fashion runway stage. then, the model from <IMAGE_1> walks in from the back of the shot from the white opening, and gracefully walk out onto the front of the white stage platform. they wear the shirt from <IMAGE_2> and black flared jeans. they look dramatically at the camera. high quality slow motion shot. fun, playful. skin pores. highly detailed faces. perfect shot. they reach the end of the runway and look at the camera as the camera slowly zooms. subtle smile.",
        "reference_images": [
            {"url": "<IMAGE_URL_1>"},
            {"url": "<IMAGE_URL_2>"},
            {"url": "<IMAGE_URL_3>"},
        ],
        "duration": 10,
        "aspect_ratio": "16:9",
        "resolution": "720p",
    },
)

request_id = response.json()["request_id"]

while True:
    result = requests.get(
        f"https://api.x.ai/v1/videos/%3C/span%3E%3Cspan%20style="color:#005CC5;--shiki-dark:#79B8FF">{request_id}",
        headers={"Authorization": headers["Authorization"]},
    )
    data = result.json()
    if data["status"] == "done":
        print(data["video"]["url"])
        break
    elif data["status"] == "expired":
        print("Request expired")
        break
    time.sleep(5)

import { xai, type XaiVideoModelOptions } from "@ai-sdk/xai";
import { experimental_generateVideo as generateVideo } from "ai";

const result = await generateVideo({
    model: xai.video("grok-imagine-video"),
    prompt: "slow zoom in on the white fashion runway stage. then, the model from <IMAGE_1> walks in from the back of the shot from the white opening, and gracefully walk out onto the front of the white stage platform. they wear the shirt from <IMAGE_2> and black flared jeans. they look dramatically at the camera. high quality slow motion shot. fun, playful. skin pores. highly detailed faces. perfect shot. they reach the end of the runway and look at the camera as the camera slowly zooms. subtle smile.",
    duration: 10,
    aspectRatio: "16:9",
    providerOptions: {
        xai: {
            mode: "reference-to-video",
            referenceImageUrls: [
                "<IMAGE_URL_1>",
                "<IMAGE_URL_2>",
                "<IMAGE_URL_3>",
            ],
            resolution: "720p",
            pollTimeoutMs: 600000,
        } satisfies XaiVideoModelOptions,
    },
});

const videoUrl = result.providerMetadata?.xai?.videoUrl;
console.log(videoUrl);

curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "slow zoom in on the white fashion runway stage. then, the model from <IMAGE_1> walks in from the back of the shot from the white opening, and gracefully walk out onto the front of the white stage platform. they wear the shirt from <IMAGE_2> and black flared jeans. they look dramatically at the camera. high quality slow motion shot. fun, playful. skin pores. highly detailed faces. perfect shot. they reach the end of the runway and look at the camera as the camera slowly zooms. subtle smile.",
    "reference_images": [
      {"url": "<IMAGE_URL_1>"},
      {"url": "<IMAGE_URL_2>"},
      {"url": "<IMAGE_URL_3>"}
    ],
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

Extend Existing Videos

Extend an existing video by providing a source video and a text prompt describing what should happen next. The result is a single video that picks up seamlessly from the last frame of the input and continues with the generated content.

The input video must have the .mp4 extension and be encoded with .mp4 supported codecs such as H.265 / H.264 / AV1, etc.
The input video duration must be between 2 and 15 seconds.
The extension duration range is 2–10 seconds (default: 6).
The aspect_ratio and resolution parameters are not supported for video extension — the output matches the aspect ratio and resolution of the input (capped at 720p).

The duration parameter controls the length of the extended portion only, not the total output. For example, if your input video is 10 seconds and you set duration to 5, the returned video will be 15 seconds long (10s original + 5s extension).

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client.video.extend(
    prompt="The shot pans to an over the shoulder perspective. Calm controlled scene.",
    model="grok-imagine-video",
    video_url="<VIDEO_URL>",
    duration=10,
)

print(response.url)

import os
import time
import requests

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
}

response = requests.post(
    "https://api.x.ai/v1/videos/extensions",
    headers=headers,
    json={
        "model": "grok-imagine-video",
        "prompt": "The shot pans to an over the shoulder perspective. Calm controlled scene.",
        "duration": 10,
        "video": {"url": "<VIDEO_URL>"},
    },
)

request_id = response.json()["request_id"]

while True:
    result = requests.get(
        f"https://api.x.ai/v1/videos/%3C/span%3E%3Cspan%20style="color:#005CC5;--shiki-dark:#79B8FF">{request_id}",
        headers={"Authorization": headers["Authorization"]},
    )
    data = result.json()
    if data["status"] == "done":
        print(data["video"]["url"])
        break
    elif data["status"] == "expired":
        print("Request expired")
        break
    time.sleep(5)

import { xai, type XaiVideoModelOptions } from "@ai-sdk/xai";
import { experimental_generateVideo as generateVideo } from "ai";

const source = await 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;

const extended = await generateVideo({
    model: xai.video("grok-imagine-video"),
    prompt: "The cat turns its head, notices a butterfly, and leaps off.",
    duration: 6,
    providerOptions: {
        xai: {
            mode: "extend-video",
            videoUrl: sourceUrl,
            pollTimeoutMs: 600000,
        } satisfies XaiVideoModelOptions,
    },
});

const extendedVideoUrl = extended.providerMetadata?.xai?.videoUrl;
console.log(extendedVideoUrl);

curl -X POST https://api.x.ai/v1/videos/extensions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "The shot pans to an over the shoulder perspective. Calm controlled scene.",
    "duration": 10,
    "video": {"url": "<VIDEO_URL>"}
  }'

Video editing uses the /v1/videos/edits endpoint and client.video.generate(video_url=...) in the Python SDK. In the AI SDK, set providerOptions.xai.mode to "edit-video" or "extend-video" and pass providerOptions.xai.videoUrl. The same asynchronous polling pattern applies to both flows, and the AI SDK returns the xAI-hosted output URL in providerMetadata.xai.videoUrl.

Configuration

The video generation API lets you control the output format of your generated videos. You can specify the duration, aspect ratio, and resolution to match your specific use case.

Duration

Control video length with the duration parameter. The allowed range is 1–15 seconds.

Video editing does not support custom duration. The edited video retains the duration of the original, which is capped at 8.7 seconds.

Aspect Ratio

Ratio	Use case
`1:1`	Social media, thumbnails
`16:9` / `9:16`	Widescreen, mobile, stories (default: `16:9`)
`4:3` / `3:4`	Presentations, portraits
`3:2` / `2:3`	Photography

For image-to-video generation, the output defaults to the input image's aspect ratio. If you specify the aspect_ratio parameter, it will override this and stretch the image to the desired aspect ratio.

Video editing does not support custom aspect_ratio — the output matches the input video's aspect ratio.

Resolution

Resolution	Description
`720p`	HD quality
`480p`	Standard definition, faster processing (default)

Video editing does not support custom resolution. The output resolution matches the input video's resolution, capped at 720p (e.g., a 1080p input will be downsized to 720p).

Example

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client.video.generate(
    prompt="Timelapse of a flower blooming in a sunlit garden",
    model="grok-imagine-video",
    duration=10,
    aspect_ratio="16:9",
    resolution="720p",
)

print(f"Video URL: {response.url}")
print(f"Duration: {response.duration}s")

import os
import time
import requests

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
}

response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    headers=headers,
    json={
        "model": "grok-imagine-video",
        "prompt": "Timelapse of a flower blooming in a sunlit garden",
        "duration": 10,
        "aspect_ratio": "16:9",
        "resolution": "720p",
    },
)

request_id = response.json()["request_id"]

while True:
    result = requests.get(
        f"https://api.x.ai/v1/videos/%3C/span%3E%3Cspan%20style="color:#005CC5;--shiki-dark:#79B8FF">{request_id}",
        headers={"Authorization": headers["Authorization"]},
    )
    data = result.json()
    if data["status"] == "done":
        print(f"Video URL: {data['video']['url']}")
        print(f"Duration: {data['video']['duration']}s")
        break
    elif data["status"] == "expired":
        print("Request expired")
        break
    time.sleep(5)

import { xai } from "@ai-sdk/xai";
import { experimental_generateVideo as generateVideo } from "ai";

const result = await generateVideo({
    model: xai.video("grok-imagine-video"),
    prompt: "Timelapse of a flower blooming in a sunlit garden",
    duration: 10,
    aspectRatio: "16:9",
    providerOptions: {
        xai: { resolution: "720p" },
    },
});

const videoUrl = result.providerMetadata?.xai?.videoUrl;
console.log(videoUrl);

curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "Timelapse of a flower blooming in a sunlit garden",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

Request Modes

The video generation endpoint supports multiple modes, determined by which fields are set. Only one mode can be active per request:

Mode	REST API fields	AI SDK shape	Description
Text-to-video	`prompt` only	`prompt: "..."`	Generates video from a text prompt alone.
Image-to-video	`prompt` + `image`	`prompt: { image, text }`	Generates video with the provided image as the starting frame.
Reference-to-video	`prompt` + `reference_images`	`prompt: "..."` + `providerOptions.xai.{ mode: "reference-to-video", referenceImageUrls }`	Generates video guided by one or more reference images.
Edit-video	`/v1/videos/edits` + `video_url`	`prompt: "..."` + `providerOptions.xai.{ mode: "edit-video", videoUrl }`	Modifies an existing video based on the prompt.
Extend-video	`/v1/videos/extensions` + `video`	`prompt: "..."` + `providerOptions.xai.{ mode: "extend-video", videoUrl }`	Extends an existing video from its last frame.

The following combination is not allowed and will return a 400 Bad Request error:

image + reference_images — use one or the other
Mixing mode values in the AI SDK — each request supports exactly one of "edit-video", "extend-video", or "reference-to-video"

When you omit mode, the AI SDK uses standard generation.

Customize Polling Behavior

When using the SDK's generate() or extend() methods, you can control how long to wait and how frequently to check for results:

Python SDK	AI SDK (`providerOptions.xai`)	Description	Default
`timeout`	`pollTimeoutMs`	Maximum time to wait for the video to complete	10 minutes
`interval`	`pollIntervalMs`	Time between status checks	100 milliseconds

import os
from datetime import timedelta
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client.video.generate(
    prompt="Epic cinematic drone shot flying through mountain peaks",
    model="grok-imagine-video",
    duration=15,
    timeout=timedelta(minutes=15),  # Wait up to 15 minutes
    interval=timedelta(seconds=5),  # Check every 5 seconds
)

print(response.url)

import { xai } from "@ai-sdk/xai";
import { experimental_generateVideo as generateVideo } from "ai";

const result = await generateVideo({
    model: xai.video("grok-imagine-video"),
    prompt: "Epic cinematic drone shot flying through mountain peaks",
    duration: 15,
    providerOptions: {
        xai: {
            pollTimeoutMs: 15 * 60 * 1000,  // Wait up to 15 minutes
            pollIntervalMs: 5 * 1000,        // Check every 5 seconds
        },
    },
});

const videoUrl = result.providerMetadata?.xai?.videoUrl;
console.log(videoUrl);

If the video isn't ready within the timeout period, the Python SDK raises a TimeoutError and the AI SDK aborts via its AbortSignal. For even finer control, use the manual polling approach — the Python SDK provides start() and get() methods, while the AI SDK supports a custom abortSignal for cancellation.

Handle Polling Manually

For fine-grained control over the generation lifecycle, use start() or extend_start() to initiate generation/extension requests respectively and get() to check status.

The get() method returns a response with a status field. Import the status enum from the SDK:

import os
import time
import xai_sdk
from xai_sdk.proto import deferred_pb2

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

# Start the generation request
start_response = client.video.start(
    prompt="A cat lounging in a sunbeam, tail gently swishing",
    model="grok-imagine-video",
    duration=5,
)

print(f"Request ID: {start_response.request_id}")

# Poll for results
while True:
    result = client.video.get(start_response.request_id)
    
    if result.status == deferred_pb2.DeferredStatus.DONE:
        print(f"Video URL: {result.response.video.url}")
        break
    elif result.status == deferred_pb2.DeferredStatus.EXPIRED:
        print("Request expired")
        break
    elif result.status == deferred_pb2.DeferredStatus.FAILED:
        print("Video generation failed")
        break
    elif result.status == deferred_pb2.DeferredStatus.PENDING:
        print("Still processing...")
        time.sleep(5)

import os
import time
import requests

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
}

# Step 1: Start generation
response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    headers=headers,
    json={
        "model": "grok-imagine-video",
        "prompt": "A cat lounging in a sunbeam, tail gently swishing",
        "duration": 5,
    },
)

request_id = response.json()["request_id"]
print(f"Request ID: {request_id}")

# Step 2: Poll for results
while True:
    result = requests.get(
        f"https://api.x.ai/v1/videos/%3C/span%3E%3Cspan%20style="color:#005CC5;--shiki-dark:#79B8FF">{request_id}",
        headers={"Authorization": headers["Authorization"]},
    )
    data = result.json()

    if data["status"] == "done":
        print(f"Video URL: {data['video']['url']}")
        break
    elif data["status"] == "expired":
        print("Request expired")
        break
    elif data["status"] == "failed":
        print("Video generation failed")
        break
    else:
        print("Still processing...")
        time.sleep(5)

// Step 1: Start generation
const response = await fetch("https://api.x.ai/v1/videos/generations", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${process.env.XAI_API_KEY}`,
    },
    body: JSON.stringify({
        model: "grok-imagine-video",
        prompt: "A cat lounging in a sunbeam, tail gently swishing",
        duration: 5,
    }),
});

const { request_id } = await response.json();
console.log(`Request ID: ${request_id}`);

// Step 2: Poll for results
while (true) {
    const result = await fetch(`https://api.x.ai/v1/videos/${request_id}`, {
        headers: { "Authorization": `Bearer ${process.env.XAI_API_KEY}` },
    });

    const data = await result.json();

    if (data.status === "done") {
        console.log(`Video URL: ${data.video.url}`);
        break;
    } else if (data.status === "expired") {
        console.log("Request expired");
        break;
    } else if (data.status === "failed") {
        console.log("Video generation failed");
        break;
    } else {
        console.log("Still processing...");
        await new Promise(resolve => setTimeout(resolve, 5000));
    }
}

# Step 1: Start generation
curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A cat lounging in a sunbeam, tail gently swishing",
    "duration": 5
  }'

# Response: {"request_id": "{request_id}"}

# Step 2: Poll for results
curl -X GET https://api.x.ai/v1/videos/{request_id} \
  -H "Authorization: Bearer $XAI_API_KEY"

The available status values are:

Proto Value	Description
`deferred_pb2.DeferredStatus.PENDING`	Video is still being generated
`deferred_pb2.DeferredStatus.DONE`	Video is ready
`deferred_pb2.DeferredStatus.EXPIRED`	Request has expired
`deferred_pb2.DeferredStatus.FAILED`	Video generation failed

Error Handling

When using the SDK's generate() or extend() methods, video generation failures are raised as a VideoGenerationError exception. This exception includes a code and message describing what went wrong. Import it from xai_sdk.video:

Python

import os
import xai_sdk
from xai_sdk.video import VideoGenerationError

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

try:
    response = client.video.generate(
        prompt="A cat lounging in a sunbeam, tail gently swishing",
        model="grok-imagine-video",
        duration=5,
    )
    print(response.url)
except VideoGenerationError as e:
    print(f"Error code: {e.code}")
    print(f"Error message: {e.message}")

The VideoGenerationError exception has the following attributes:

Attribute	Type	Description
`code`	`str`	An error code identifying the failure reason
`message`	`str`	A human-readable message describing the failure

You can combine this with TimeoutError handling for comprehensive error coverage:

Python

import os
import xai_sdk
from xai_sdk.video import VideoGenerationError

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

try:
    response = client.video.generate(
        prompt="A cat lounging in a sunbeam, tail gently swishing",
        model="grok-imagine-video",
        duration=5,
    )
    print(response.url)
except VideoGenerationError as e:
    print(f"Generation failed [{e.code}]: {e.message}")
except TimeoutError:
    print("Generation timed out — try increasing the timeout or simplifying the prompt")

Response Details

The SDK response includes the generated video and provider-specific metadata. In the AI SDK, the xAI-hosted output URL is available at providerMetadata.xai.videoUrl.

if response.respect_moderation:
    print(response.url)
else:
    print("Video filtered by moderation")

print(f"Duration: {response.duration} seconds")
print(f"Model: {response.model}")

const result = await generateVideo({
    model: xai.video("grok-imagine-video"),
    prompt: "A futuristic city skyline at dusk",
    duration: 5,
});

console.log(result.providerMetadata?.xai?.videoUrl);

Concurrent Requests

When you need to generate multiple videos or apply several edits to the same source video, run requests concurrently. This is especially useful for branching multiple edits from the same intermediate result.

The examples below show both Python concurrency and the AI SDK pattern for chaining one edit into concurrent follow-up edits.

import os
import asyncio
import xai_sdk

async def edit_concurrently():
    client = xai_sdk.AsyncClient(api_key=os.getenv("XAI_API_KEY"))

    source_video = "https://data.x.ai/docs/video-generation/portrait-wave.mp4"

    prompts = [
        "Give the woman a silver necklace",
        "Change the color of the woman's outfit to red",
        "Give the woman a wide-brimmed black hat",
    ]

    tasks = [
        client.video.generate(
            prompt=prompt,
            model="grok-imagine-video",
            video_url=source_video,
        )
        for prompt in prompts
    ]

    results = await asyncio.gather(*tasks)

    for prompt, result in zip(prompts, results):
        print(f"{prompt}: {result.url}")

asyncio.run(edit_concurrently())

import { xai, type XaiVideoModelOptions } from "@ai-sdk/xai";
import { experimental_generateVideo as generateVideo } from "ai";

const providerOptions = {
    xai: {
        mode: "edit-video",
        videoUrl: "https://example.com/source-video.mp4",
        pollTimeoutMs: 600000,
    } satisfies XaiVideoModelOptions,
};

const step1 = await generateVideo({
    model: xai.video("grok-imagine-video"),
    prompt: "Add a party hat to the person",
    providerOptions,
});

const step1VideoUrl = step1.providerMetadata?.xai?.videoUrl as string;

const [withSunglasses, withScarf] = await Promise.all([
    generateVideo({
        model: xai.video("grok-imagine-video"),
        prompt: "Add sunglasses",
        providerOptions: {
            xai: {
                mode: "edit-video",
                videoUrl: step1VideoUrl,
                pollTimeoutMs: 600000,
            } satisfies XaiVideoModelOptions,
        },
    }),
    generateVideo({
        model: xai.video("grok-imagine-video"),
        prompt: "Add a scarf",
        providerOptions: {
            xai: {
                mode: "edit-video",
                videoUrl: step1VideoUrl,
                pollTimeoutMs: 600000,
            } satisfies XaiVideoModelOptions,
        },
    }),
]);

console.log(withSunglasses.providerMetadata?.xai?.videoUrl);
console.log(withScarf.providerMetadata?.xai?.videoUrl);

Pricing

Video generation uses per-second pricing. Longer videos cost more, and both duration and resolution affect the total cost.

For full pricing details on the grok-imagine-video model, see the model page.

Limitations

Maximum duration: 15 seconds for generation, 8.7 seconds for editing input videos, 2–10 seconds for video extensions (input video must be 2–15 seconds)
URL expiration: Generated URLs are ephemeral and should not be relied upon for long-term storage
Resolutions: 480p or 720p
Content moderation: Videos are subject to content policy review

Models — Available video models and pricing
Image Generation — Generate still images from text
API Reference — Full endpoint documentation
Imagine API Landing Page — Showcase of the Imagine API in action

Did you find this page helpful?

Last updated: April 2, 2026