Multi-Image Editing and References

Updated November 2, 2026 — Imagine. grok-imagine-image-quality was removed as of November 2, 2026 (requests are now handled by Imagine 2.0 in low quality): examples now use grok-imagine-image (Imagine 1.0) and grok-imagine-image-2.0 (Imagine 2.0, low, medium, or auto quality). With the OpenAI SDK, aspect_ratio, resolution, and quality are passed via extra_body, and editing is handled via the xAI SDK or an HTTP request.

Working with Multiple Source Images

One of the strengths of the edit endpoint is the ability to provide up to 5 reference images in a single request. This opens up advanced creative possibilities: combining elements from multiple sources, blending styles, or creating complex compositions.

The `images` Parameter (Plural)

Switching from image to images changes more than the parameter shape: it changes what you ask the model to do. With one source, it modifies an image; with multiple, it must arbitrate between them—deciding what to take from each. It will arbitrate regardless; the only question is whether you direct that process, which is the focus of the next section.

Note that the two parameters are mutually exclusive: image (single object) and images (array) cannot be combined.

import requests
import os

headers = {
    "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
    "Content-Type": "application/json"
}

payload = {
    "model": "grok-imagine-image",
    "prompt": "Combine the character from the first image with "
              "the landscape from the second image",
    "images": [
        {"url": "https://exemple.com/personnage.jpg"},
        {"url": "https://exemple.com/paysage.jpg"}
    ]
}

response = requests.post(
    "https://api.x.ai/v1/images/edits",
    headers=headers,
    json=payload
).json()

Referencing Images in the Prompt

When you provide multiple images, you can reference them individually in your prompt using the syntax <IMAGE_0>, <IMAGE_1>, etc. The index starts at 0.

payload = {
    "model": "grok-imagine-image",
    "prompt": "Place the product from <IMAGE_0> on the table from <IMAGE_1>, "
              "with the ambient lighting from <IMAGE_2>",
    "images": [
        {"url": "https://exemple.com/produit.jpg"},      # <IMAGE_0>
        {"url": "https://exemple.com/table.jpg"},         # <IMAGE_1>
        {"url": "https://exemple.com/ambiance.jpg"}       # <IMAGE_2>
    ]
}

This syntax is what distinguishes a controlled composition from an approximate blend. “Combine these images” leaves everything up to the model; “place the product from <IMAGE_0> in the setting of <IMAGE_1> while keeping the lighting from <IMAGE_1>” leaves no room for interpretation. As soon as you provide more than one source, reference them explicitly.

Use Cases with Multiple Images

Style Transfer

Apply the style of a reference image to another:

payload = {
    "model": "grok-imagine-image-2.0",
    "prompt": "Reproduce the content of <IMAGE_0> in the artistic style of <IMAGE_1>",
    "images": [
        {"url": "https://exemple.com/photo-originale.jpg"},
        {"url": "https://exemple.com/reference-style.jpg"}
    ]
}

Product Composition

Integrate a product into a setting with reference lighting:

payload = {
    "model": "grok-imagine-image-2.0",
    "prompt": "Photograph the product from <IMAGE_0> placed on the furniture from <IMAGE_1> "
              "in the room from <IMAGE_2>, consistent natural lighting",
    "images": [
        {"url": "https://exemple.com/produit-detouré.png"},
        {"url": "https://exemple.com/meuble.jpg"},
        {"url": "https://exemple.com/piece.jpg"}
    ]
}

Face and Background Fusion

Combine a portrait with a specific background:

payload = {
    "model": "grok-imagine-image",
    "prompt": "Place the person from <IMAGE_0> in front of the building from <IMAGE_1>, "
              "keeping natural lighting and perspective",
    "images": [
        {"url": "https://exemple.com/portrait.jpg"},
        {"url": "https://exemple.com/batiment.jpg"}
    ]
}

Limits and Best Practices

The technical limit is 5 images per request, and you can freely mix formats—some sources as URLs, others as Base64—in the same array. The real difficulty isn’t there: it lies in prompt precision, which must grow with the number of images. With two sources, “combine the character and the setting” often suffices; with five, the model can no longer guess which element to take from which image, and this is exactly the role of the <IMAGE_1> to <IMAGE_5> references: “place the logo from <IMAGE_2> on the character’s t-shirt from <IMAGE_1>, in the lighting ambiance of <IMAGE_3>” leaves no ambiguity. For complex multi-source compositions, the pro model (grok-imagine-image-quality) justifies its extra cost: this is precisely where the gap with the standard model is most visible, in consistency between heterogeneous elements.

Hands-On Practice

Try combining two images you have on hand:

payload = {
    "model": "grok-imagine-image",
    "prompt": "Create a scene where the object from <IMAGE_0> floats in the sky from <IMAGE_1>, "
              "surrealist style",
    "images": [
        {"url": "URL_OF_YOUR_FIRST_IMAGE"},
        {"url": "URL_OF_YOUR_SECOND_IMAGE"}
    ],
    "n": 3
}

Generate 3 variations to compare the model’s interpretations.

Key Takeaways

The images parameter accepts up to 5 source images in an array
image (singular) and images (plural) are mutually exclusive
The syntax <IMAGE_0>, <IMAGE_1> allows you to reference each image in the prompt
Use cases include style transfer, composition, and fusion
Be precise in your prompt when using multiple sources