Generate a video from text with the Imagine API

Call the Imagine video API with a text prompt alone when you need a short clip and do not have a starting still yet. Official Video Generation documents text-to-video on POST https://api.x.ai/v1/videos/generations with model grok-imagine-video-1.5, which also supports native 1080p for this mode. Create a key and load credits at console.x.ai before you bill the first run. On grok-imagine-video, text-to-video still runs as text-to-image then image-to-video under the hood in a single request; the intermediate still is not returned.

What you need

An XAI_API_KEY with Console balance, a prompt that names the subject, motion, camera move, and light, and a plan for duration (1–15 seconds), aspect ratio, and resolution. If you already have a still that should be the first frame, use Animate a still with the Imagine API instead. Consumer Video 1.5 Fast on grok.com/imagine is a separate meter from Console API spend.

Generate from a prompt

1. Export the key locally and keep it out of chat logs and public repos:

export XAI_API_KEY="your_api_key"

2. Prefer the xAI Python SDK when you want the client to poll for you:

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-1.5",
    duration=10,
    aspect_ratio="16:9",
    resolution="720p",
)

print(response.url)
print(response.duration)

3. Or start and poll yourself over REST when you need the request_id in your own queue:

REQUEST_ID=$(curl -s -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-1.5",
    "prompt": "A glowing crystal-powered rocket launching from the red dunes of Mars",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }' | jq -r '.request_id')

while true; do
  RESULT=$(curl -s "https://api.x.ai/v1/videos/$REQUEST_ID" \
    -H "Authorization: Bearer $XAI_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.status')
  if [ "$STATUS" = "done" ]; then
    echo "$RESULT" | jq -r '.video.url'
    break
  elif [ "$STATUS" = "failed" ] || [ "$STATUS" = "expired" ]; then
    echo "Request $STATUS"; echo "$RESULT" | jq .
    break
  fi
  sleep 5
done

4. Download the temporary URL promptly; video generation can take up to several minutes depending on prompt complexity, duration, and resolution.
5. Pin length with Set duration on Imagine API videos when you are budgeting per-second pricing, and pass resolution (480p, 720p, or 1080p on grok-imagine-video-1.5 text-to-video) when the placement needs sharper output than the 480p default.

After the generate

Open the clip and check motion, audio, and framing before you spend another run. Pass generate_audio=false (SDK) or "generate_audio": false (REST) when you need a silent file for your own soundtrack. If a region of the finished clip is wrong, edit from the output URL with Edit a video with the Imagine API. For character or product consistency without locking the first frame, use reference images on the same model family instead of inventing a second product path.

Pitfalls

Leaving duration unset bills the service default (8 seconds in the REST reference) when a shorter cut would have been enough. Asking for 1080p on a model or mode that does not support it fails with a precondition error. Letting temporary video URLs expire before download loses a paid generation. Mixing Console API spend with SuperGrok weekly Imagine quotas on grok.com confuses two different meters. Pasting keys into tickets or committing them to git forces a rotate.