Animate an image to video with the Imagine API

Same endpoint as text-to-video: POST https://api.x.ai/v1/videos/generations with prompt plus image. The still is the starting frame. An optional prompt steers the motion. image can be a public URL, a data URI, or a Files API file_id. Model grok-imagine-video-1.5 supports 1080p on this path.

Output defaults to the input image's aspect ratio. Setting aspect_ratio stretches to that ratio.

Start and poll

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": "Make the water crash down and slowly pan out the camera",
    "image": {"url": "https://docs.x.ai/assets/api-examples/video/waterfall-still.png"},
    "duration": 12,
    "resolution": "1080p"
  }' | 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

Data URI: "image": {"url": "data:image/jpeg;base64,..." }. Files API: "image": {"file_id": "file_..."}. Do not send image and reference_images together (400). reference_images steers a generated first frame; it does not lock the opening still.

Python SDK polls for you with image_url= or image_file_id=.

Pitfalls

• Setting aspect_ratio stretches the source still. Omit it to keep the input ratio.
• image plus reference_images is a 400.
• Output URLs expire. Download the file.
• Console API credits are a separate bill from SuperGrok's weekly pool on grok.com.