Edit with multiple source images on Imagine

POST https://api.x.ai/v1/images/edits accepts up to five source images in one edit. Order in the request is the order the model sees. Default output aspect ratio follows the first input; override with aspect_ratio (for example "1:1" or "16:9"). Each source can be a public URL, a base64 data URI, or a Files API file_id, and you can mix kinds. Single-image edits: Edit an image with the Imagine API.

Mix file_id and 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": "Blend these two scenes into one cohesive composition",
    "images": [
      { "file_id": "file_7de029f4-eb66-42ee-87f8-b2a9d9e7466a" },
      { "url": "https://example.com/scene-b.jpg" }
    ],
    "aspect_ratio": "16:9",
    "response_format": "url"
  }'

xAI SDK

import os
import xai_sdk

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

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",
    ],
)
print(response.url)

OpenAI SDK images.edit() is not supported for xAI image editing (multipart vs JSON). Use the xAI SDK, Vercel AI SDK, or raw HTTP. Persist the result with storage_options when you need a stable file_id (Persist an Imagine output with a public URL).

Pitfalls

• More than five sources in one edit.
• Assuming aspect ratio always matches every input; only the first sets the default unless you pass aspect_ratio.
• Referencing a Files id that is still uploading or the wrong media type (images: PNG/JPEG/WebP).
• Console API credits are a separate bill from SuperGrok's weekly pool on grok.com.