Endpoint /v1/images/edits: Edit Your Images

Updated November 2, 2026 — Imagine. grok-imagine-image-quality was removed on November 2, 2026 (its requests are served by Imagine 2.0 at 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 go through extra_body, and editing uses the xAI SDK or an HTTP request.

Image Editing with the Grok API

Beyond generation, the xAI API offers a dedicated endpoint for editing existing images: POST /v1/images/edits. This endpoint lets you modify, transform, or enhance images by describing the desired changes in a simple text prompt.

Edit Request Structure

Editing works like generation, with one difference that changes everything about how you write prompts: the prompt describes the modification, not the final image. “A woman with sunglasses” regenerates an entire image; “add sunglasses” keeps the photo and intervenes only on that point. This is the most common confusion on the first try, and it explains most disappointing results.

import requests
import os

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

payload = {
    "model": "grok-imagine-image",
    "prompt": "Add a red hat to the character",
    "image": {
        "url": "https://exemple.com/photo-personnage.jpg"
    }
}

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

result = response.json()
edited_url = result["data"][0]["url"]

Why Use requests Instead of the OpenAI SDK?

Here’s the technical pitfall of this lesson, and you’ll want to know this before wasting an hour on it: compatibility with the OpenAI SDK, which works perfectly for generation, stops at editing. The xAI edit endpoint uses a JSON format, while the SDK’s images.edit() method sends multipart/form-data. This content-type incompatibility means you must use the REST API directly with the requests library for edits.

# DOES NOT WORK with the xAI API
# client.images.edit(...)  # Sends multipart, not JSON

# WORKS: direct REST call
requests.post(
    "https://api.x.ai/v1/images/edits",
    headers=headers,
    json=payload
)

Edit Endpoint Parameters

• model (required): grok-imagine-image (Imagine 1.0) or grok-imagine-image-2.0 (Imagine 2.0, which also accepts quality)
• prompt (required): description of the modification to apply
• image: object containing the URL of a single source image
• images: array of objects for multiple source images (mutually exclusive with image)
• mask: object containing the URL of the area mask to edit
• n: number of variants to generate (1 to 10)
• response_format: url or b64_json

Types of Possible Edits

The five families below don’t share the same success rate, and it helps to know this before promising a result. Adding elements and changing ambiance work very well because they rely on existing content. Removal is trickier—the model must reconstruct what was behind the removed element—and this is where the mask becomes essential, by precisely delimiting the area to recalculate.

• Adding elements: “Add sunglasses to the character”
• Removal: “Remove the background and replace it with a white background”
• Style transformation: “Convert this photo into a watercolor illustration”
• Ambiance modification: “Change the scene from day to night”
• Correction: “Improve the lighting and increase the contrast”

# Example: change an image's style
payload = {
    "model": "grok-imagine-image",
    "prompt": "Transform this photo into a Franco-Belgian comic book style illustration",
    "image": {
        "url": "https://exemple.com/photo-ville.jpg"
    }
}

Hands-On Practice

Try editing an image in multiple steps. Start with a simple modification, then refine:

# Step 1: modify the background
payload_step1 = {
    "model": "grok-imagine-image",
    "prompt": "Replace the background with a sunset over the ocean",
    "image": {"url": "https://exemple.com/portrait.jpg"}
}

Key Takeaways

• The edit endpoint is POST /v1/images/edits
• Use requests in Python, not the OpenAI SDK (format incompatibility)
• You can provide up to 5 source images per request
• The prompt describes the desired modification in natural language
• Both models (Imagine 1.0 and Imagine 2.0) are available for editing; with the OpenAI SDK, images.edit() is not supported by xAI: use the xAI SDK or an HTTP request