Use the Files API with Imagine

Anywhere Imagine accepts a public URL or a data URI, you can send a Files API file_id instead. Set storage_options on the same request to save the output. Default image URLs on imgen.x.ai and video URLs on vidgen.x.ai expire.

Edit a stored still

curl -s -X POST https://api.x.ai/v1/images/edits \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-quality",
    "prompt": "Add a party hat to the dog",
    "image": { "file_id": "file_7de029f4-eb66-42ee-87f8-b2a9d9e7466a" },
    "response_format": "url"
  }'

Python with the official SDK:

import os
import xai_sdk

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

gen = client.image.sample(
    prompt="A futuristic city skyline at night",
    model="grok-imagine-image-quality",
    storage_options={"filename": "city.jpg"},
)
city = gen.file_output.file_id

edit = client.image.sample(
    prompt="Add neon signs to the buildings",
    model="grok-imagine-image-quality",
    image_file_id=city,
    storage_options={"filename": "city-neon.jpg"},
)

vid = client.video.generate(
    prompt="A camera pulls back through the city",
    model="grok-imagine-video-1.5",
    duration=5,
    image_file_id=edit.file_output.file_id,
)
print(vid.url)

storage_options.filename is required to persist. Omit public_url and the file stays private. Mix file_id and url in a multi-image images[] array. Video edits take video: { "file_id": "..." } on /v1/videos/edits. Image-to-video takes image: { "file_id": "..." } on /v1/videos/generations.

Images must be PNG, JPEG, or WebP. Videos must be MP4 and fully uploaded before you reference them.

Pitfalls

• file_id and url on the same image or video object are mutually exclusive.
• The ephemeral Imagine URL is always returned. file_output.file_id is the stable copy. file_output.public_url appears only when you asked for one.
• If public URL creation fails, the file can still be stored. Read public_url_error.
• Console API credits are a separate bill from SuperGrok's weekly pool on grok.com.