GPT Image 2.5 mask_url edit: change one region, keep the rest

To change only part of an image, pass the photo in input_references and a second image as mask_url on openai/gpt-image-2.5. The Sume docs list mask_url as an optional public HTTPS mask URL for ChatGPT Image 2.5 edits (Image API docs), so treat it as a GPT Image 2.5 option and do not send it to other models. The prompt then describes what should appear in the masked area.

I could not confirm from Sume's docs which mask color marks the edit zone, so test with a small image first and flip the mask if the wrong region changes.

What does each piece do?

Read 2026-10-01.

How do I build the mask?

Make a black image the size of your photo and fill the region you want changed with white. Save as PNG, upload it somewhere public, and use that URL.

from PIL import Image, ImageDraw

W, H = 1024, 1024
mask = Image.new("L", (W, H), 0)
draw = ImageDraw.Draw(mask)
draw.rectangle((300, 600, 724, 900), fill=255)
mask.save("mask.png")
print("mask.png", mask.size, "white box = region to change")

How do I test it?

Generate with a low-cost setting first: set quality to low and look at which region changed. If it is the inverse, invert the mask with ImageOps.invert. Then raise quality for the final. Keep the prompt narrow ('replace the mug with a blue ceramic mug') and avoid asking for global changes, which fight the mask.

Good first edits to try

Start with objects that have clear edges: swap a mug, change a sign, remove a small item by asking for the surrounding surface to continue. Avoid faces and hands for the first test; they expose seams and anatomy errors that make it hard to judge whether the mask itself works.

Limits

The mask must be reachable by the API at a public HTTPS URL, so a local file path will not work. Edges of a hard rectangle can show a seam; blur the mask edge by a few pixels. The mask convention is not spelled out in what I read, which is why the test step matters. Prices on fal are a vendor reference only; Sume bills its own price in usage.cost.