English Docs
API Console

Model Capabilities

Referencing Files as Input

View as Markdown
Create API key Learn Grok 4.7

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

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-2.0",
    "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

# 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-2.0",
    "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

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

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

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

Last updated:November 2, 2026