Guides

Video Generations

All video generation/edit requests are deferred requests, where a user sends a video generation/edit request, get a response with a request ID, and retrieve the video result later using the request ID. If you're using our SDK, it can handle the polling of the result automatically.

Generate/Edit a Video with Automatic Polling

For easiness of use, our SDK can automatically send the video generation/edit request, and poll for the response until the result is available, or if the request has failed.

Generate a video directly from a text prompt:

Python

from xai_sdk import Client

client = Client()

response = client.video.generate(
    prompt="A cat playing with a ball",
    model="grok-imagine-video",
)
print(f"Video URL: {response.url}")

Generate a video from a user-provided image:

Python

from xai_sdk import Client

client = Client()

response = client.video.generate(
    prompt="Generate a video based on the provided image.",
    model="grok-imagine-video",
    image_url=<url of the image>,
)
print(f"Video URL: {response.url}")

Edit an existing video:

Python

from xai_sdk import Client

client = Client()

response = client.video.generate(
    prompt="Make the ball larger.",
    model="grok-imagine-video",
    video_url=<url of the video to edit>,
)
print(f"Video URL: {response.url}")

Send a Video Generation Request

If you do not want to use our SDK, or prefer to send a request and retrieve the result yourself, you can still send a regular video generation request. This will return a response_id which you can use to retrieve the generated video later.

Video Generation from Text

Send a request to start generating a video from a text prompt.

from xai_sdk import Client

client = Client()

response = client.video.start(
    prompt="A cat playing with a ball",
    model="grok-imagine-video",
)
print(f"Request ID: {response.request_id}")

The response includes a request_id, which you'll use to retrieve the generated video result.

Bash

{"request_id":"aa87081b-1a29-d8a6-e5bf-5807e3a7a561"}

Video Generation from Image

You can also generate a video from an existing image.

To generate from an image:

from xai_sdk import Client

client = Client()

response = client.video.start(
    prompt="Generate a video based on the provided image.",
    model="grok-imagine-video",
    image_url=<url of the image>,
)
print(f"Request ID: {response.request_id}")

Edit a Video

Provide an input video (via a publicly accessible URL) and a prompt describing the desired changes. The API will generate a new edited video based on your instructions.

Note: The input video URL must be a direct, publicly accessible link to the video file. The maximum supported video length is 8.7 seconds.

from xai_sdk import Client

client = Client()

response = client.video.start(
    prompt="Make the ball in the video larger.",
    model="grok-imagine-video",
    video_url=<url of the previous video>,
)
print(f"Request ID: {response.request_id}")

You will receive a request_id in the response body, which you can use to retrieve the edit generation result.

Bash

{"request_id":"a3d1008e-4544-40d4-d075-11527e794e4a"}

Retrieving Video Generation/Edit Results

After making a video generation or edit requests and receiving the video generation request_id, you can retrieve the results using the request_id.

# After sending the generation request and getting the request_id.

response = client.video.get(request_id)
print(f"Video URL: {response.url}")

Specifying Video Output Format

Video Duration

You can specify the duration of the generated video in seconds. The allowed range is between 1 and 15 seconds.

Video editing doesn't support user-defined duration. The edited video will have the same duration of the original video.

Using xAI SDK auto-polling:

Python

from xai_sdk import Client

client = Client()

response = client.video.generate(
    prompt="A cat playing with a ball",
    model="grok-imagine-video",
    duration=10
)
print(f"Video URL: {response.url}")
print(f"Duration: {response.duration}")

Sending normal generation request:

from xai_sdk import Client

client = Client()

response = client.video.start(
    prompt="A cat playing with a ball",
    model="grok-imagine-video",
    duration=10
)
print(f"Request ID: {response.request_id}")

Aspect Ratio

You can specify the aspect ratio of the video. The default aspect ratio is 16:9.

The following aspect ratios are supported:

16:9
4:3
1:1
9:16
3:4
3:2
2:3

Using xAI SDK auto-polling:

Python

from xai_sdk import Client

client = Client()

response = client.video.generate(
    prompt="A cat playing with a ball",
    model="grok-imagine-video",
    aspect_ratio="4:3"
)
print(f"Video URL: {response.url}")

Sending regular generation request:

from xai_sdk import Client

client = Client()

response = client.video.start(
    prompt="A cat playing with a ball",
    model="grok-imagine-video",
    aspect_ratio="4:3"
)
print(f"Request ID: {response.request_id}")

Resolution

You can select a resolution from a list of supported resolutions.

Supported resolutions:

720p
480p

Using xAI SDK auto-polling:

Python

from xai_sdk import Client

client = Client()

response = client.video.generate(
    prompt="A cat playing with a ball",
    model="grok-imagine-video",
    resolution="720p"
)
print(f"Video URL: {response.url}")

Sending regular generation request:

from xai_sdk import Client

client = Client()

response = client.video.start(
    prompt="A cat playing with a ball",
    model="grok-imagine-video",
    resolution="720p"
)
print(f"Request ID: {response.request_id}")