Anywhere an Imagine endpoint accepts a public URL or base64-encoded image/video, you can substitute a file_id from your Files API storage. The file is fetched server-side from your private storage, so:

No bandwidth uploading the same image twice — useful for iterative editing loops.
The original file stays private (no need to make it public to use it as an input).
Works with both uploaded files and assets generated by earlier Imagine calls (via storage_options).

The referenced file must be the correct content type for the endpoint (images: PNG/JPEG/WebP; videos: MP4) and must be fully uploaded.

Editing a stored image

import os
import xai_sdk

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

response = client.image.sample(
    prompt="Add a party hat to the dog",
    model="grok-imagine-image-quality",
    image_file_id="file_7de029f4-eb66-42ee-87f8-b2a9d9e7466a",  # instead of image_url
)

print(response.url)

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"
  }'

Editing with multiple stored images

response = client.image.sample(
    prompt="Blend these two scenes into one cohesive composition",
    model="grok-imagine-image-quality",
    image_file_ids=[
        "file_7de029f4-eb66-42ee-87f8-b2a9d9e7466a",
        "file_2cd998e7-bf12-44aa-92c8-e3d1f1c1234f",
    ],
)

# Each images entry independently carries url or file_id — mix kinds within a single request.
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": "Blend these two scenes into one cohesive composition",
    "images": [
      { "file_id": "file_7de029f4-eb66-42ee-87f8-b2a9d9e7466a" },
      { "url": "https://example.com/scene-b.jpg" }
    ],
    "response_format": "url"
  }'

Image-to-video from a stored first frame

response = client.video.generate(
    prompt="Pan across the scene as the sky darkens",
    model="grok-imagine-video-1.5",
    duration=5,
    image_file_id="file_7de029f4-eb66-42ee-87f8-b2a9d9e7466a",
)

print(response.url)

curl -s -X POST https://api.x.ai/v1/videos/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "Pan across the scene as the sky darkens",
    "duration": 5,
    "image": { "file_id": "file_7de029f4-eb66-42ee-87f8-b2a9d9e7466a" }
  }'

Editing a stored video

response = client.video.generate(
    prompt="Add rain and a moody atmosphere",
    model="grok-imagine-video",
    video_file_id="file_5be118c3-da55-31dd-76e7-a1b8c8d6355b",
)

curl -s -X POST https://api.x.ai/v1/videos/edits \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "Add rain and a moody atmosphere",
    "video": { "file_id": "file_5be118c3-da55-31dd-76e7-a1b8c8d6355b" }
  }'

Reference-to-video with multiple stored images

response = client.video.generate(
    prompt="A woman in this dress walks down a city street at night",
    model="grok-imagine-video-1.5",
    duration=5,
    reference_image_file_ids=[
        "file_5be118c3-da55-31dd-76e7-a1b8c8d6355b",  # subject
        "file_2cd998e7-bf12-44aa-92c8-e3d1f1c1234f",  # outfit
    ],
)

# Each reference_images entry independently carries url or file_id — mix kinds within a single request.
curl -s -X POST https://api.x.ai/v1/videos/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "A woman in this dress walks down a city street at night",
    "duration": 5,
    "reference_images": [
      { "file_id": "file_5be118c3-da55-31dd-76e7-a1b8c8d6355b" },
      { "url": "https://example.com/dress.jpg" }
    ]
  }'

Files API Integration — Overview + capstone example showing inputs and outputs together.
Persisting Generated Output — The output side: storage_options, public URLs, expiry semantics.
Managing Files — Upload, list, retrieve, update, and delete files.

Last updated:July 30, 2026

Model Capabilities

Referencing Files as Input

Editing a stored image

Editing with multiple stored images

Image-to-video from a stored first frame

Editing a stored video

Reference-to-video with multiple stored images