Grok Imagine Video API Tutorial for Beginners

The Grok video API lets developers generate video from a text prompt and, for supported workflows, a starting image or other references. Unlike a synchronous text response, video generation is asynchronous: the first request returns a job ID, and your application polls until the result is ready.

This tutorial explains the architecture and provides a minimal Python example. If you want to evaluate visual quality before building code, test prompts in Elser AI’s Grok Imagine workspace, then move the successful shot specification into the API.

What you need

an xAI developer account;
an API key stored securely;
Python 3.10 or newer;
the requests package;
durable storage for completed video files;
a budget and retry policy.

Never hard-code an API key in source control or expose it in browser-side JavaScript.

How the API workflow works

Send a generation request to /v1/videos/generations.
Receive a request_id.
Poll /v1/videos/{request_id}.
Stop when the status is done or a terminal failure occurs.
Download the returned video promptly because generated URLs are ephemeral.
Save metadata, prompt, model, settings, and cost for audit and reproducibility.

Minimal text-to-video example

import os
import time
from pathlib import Path

import requests


API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "grok-imagine-video-1.5",
    "prompt": (
        "A matte-black product case opens on a reflective surface. "
        "A soft coral light reveals the product as the camera performs "
        "a slow push-in. Premium studio lighting, realistic motion, no text."
    ),
    "duration": 6,
    "resolution": "720p",
}

create = requests.post(
    f"{BASE_URL}/videos/generations",
    headers=HEADERS,
    json=payload,
    timeout=60,
)
create.raise_for_status()
request_id = create.json()["request_id"]

deadline = time.time() + 15 * 60
while time.time() < deadline:
    status_response = requests.get(
        f"{BASE_URL}/videos/{request_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=60,
    )
    status_response.raise_for_status()
    result = status_response.json()

    if result["status"] == "done":
        video_url = result["video"]["url"]
        video_response = requests.get(video_url, timeout=180)
        video_response.raise_for_status()
        Path("output.mp4").write_bytes(video_response.content)
        print("Saved output.mp4")
        break

    if result["status"] in {"expired", "failed", "cancelled"}:
        raise RuntimeError(f"Generation ended with status: {result['status']}")

    time.sleep(5)
else:
    raise TimeoutError("Video generation did not finish before the deadline")

Check xAI’s current API schema before deployment. Model names, supported parameters, and response statuses can change.

Image-to-video

xAI’s documentation supports a public image URL or a base64 data URI for image-led generation. Conceptually, the request adds an image object:

payload = {
    "model": "grok-imagine-video-1.5",
    "prompt": (
        "Preserve the subject, clothing, and background. "
        "The subject turns toward the window while the camera slowly pushes in."
    ),
    "image": {"url": "https://example.com/source-image.png"},
    "duration": 6,
    "resolution": "720p",
}

Use short-lived signed URLs if the input is private. Do not expose customer media publicly just to satisfy an API requirement.

Production error handling

A production client should handle:

authentication failure;
validation errors;
moderation rejection;
rate limiting;
network timeouts;
expired jobs or result URLs;
duplicate submissions;
partial storage failure;
account budget exhaustion.

Use exponential backoff with jitter for retryable errors. Do not retry validation or moderation failures indefinitely. Attach an idempotency key or maintain your own job record so a network retry does not create an unexpected duplicate video.

Cost controls

xAI prices video by generated second, with rates varying by model and resolution. Media inputs can also incur charges. Store the model, resolution, duration, and returned usage data for every job.

Useful safeguards include:

maximum duration per request;
per-user daily spend caps;
lower-resolution draft mode;
approval before high-resolution rerenders;
a limit on automatic retries;
alerts for unusual generation volume;
cost per approved clip reporting.

Queue and concurrency design

Video jobs should enter a queue. Workers submit requests, poll responsibly, and transfer completed files to durable object storage. Your application database should track:

internal job ID;
xAI request ID;
user and project;
prompt and input references;
status and progress;
timestamps;
model and settings;
output storage URL;
cost and moderation outcome.

Respect current account-tier rate limits. More parallelism is not useful if it creates throttling or uncontrolled cost.

Safety and privacy

Validate that users have rights to uploaded images and permission from identifiable people. Make the system reject obvious attempts to create non-consensual intimate imagery, deceptive impersonation, exploitation, or illegal content. Retain only the media and logs needed for the service, and publish a clear deletion policy.

Do not remove provider watermarks or provenance signals. Include human review for high-reach, political, medical, financial, or identity-sensitive content.

No-code evaluation before API integration

An API project is easier when the creative specification is already proven. Use Grok Imagine Video on Elser AI to test prompts, reference-image suitability, aspect ratios, and shot acceptance criteria. Once the team can reliably describe a usable shot, automate the repeatable part.