English Docs
API Console

Model Capabilities

Files API Integration

View as Markdown
Create API key Learn Grok 4.7

The Imagine API integrates with the Files API in two directions:

Reference files as inputsUse a stored file_id instead of URL or base64 input on every Imagine endpoint.Explore Persist generated outputsSave generated Imagine images and videos to Files, with an optional shareable public URL.Explore

By default, Imagine requests return an ephemeral URL on imgen.x.ai or vidgen.x.ai that's only good for fetching the asset shortly after generation. The Files integration lets you both reuse stored inputs and persist outputs in the same request.

Putting it together: an iterative loop

The clearest payoff for using inputs and outputs together is chaining Imagine calls without ever leaving the Files API. Reference a stored file_id directly from a previous call's file_output — no need to download, re-upload, or make the file public.

Python

import os
import xai_sdk

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

# 1. Generate an image and store it
gen = client.image.sample(
    prompt="A futuristic city skyline at night",
    model="grok-imagine-image-quality",
    storage_options={"filename": "city.jpg"},  # store privately, no public URL needed
)
city = gen.file_output.file_id

# 2. Edit the stored image without re-uploading
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"},
)

# 3. Animate the edited result into a video
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)

Last updated:July 30, 2026