mask_url edit on GPT Image 2.5: the mask is a guide, not a hard edge

On GPT Image models, a mask is guidance for the model rather than a pixel-exact stencil. OpenAI's image guide says masking with GPT Image is entirely prompt-based and that the model may not follow the exact shape of the mask with complete precision. Sume exposes an optional mask_url on ChatGPT Image 2.5 edits, so test for edge bleed before you rely on it for a product photo.

How Sume takes the mask

The Image API docs say both openai/gpt-image-2.5 and openai/gpt-image-2.5-sunburst support text-to-image, up to 16 image references, an optional mask_url and background. The mask URL must be public HTTPS, like reference URLs: Sume rejects localhost, private-network and non-HTTPS URLs before submission.

A 4-cent edge-bleed test

Pick one photo and a mask that covers only the label of a bottle. Run the same edit at quality: "low" four times with n: 4 for 4 cents. Compare each result with the original outside the masked area using an image diff or a flicker toggle. If more than a few pixels change outside the mask, the mask is acting as a hint for that image, and you should composite the result back onto the original using your own mask.

Add words to the prompt as well: 'change only the label, leave everything else untouched'. OpenAI's guide describes the mask behavior as prompt-based, so the wording matters as much as the shape.

• Use aspect_ratio: "auto" so the output keeps the photo's shape.
• Feather your own composite mask by a few pixels so the seam disappears.
• Keep the masked area generous; a tight mask around small text is the hardest case.

When to composite instead

For logo and text swaps where every other pixel must stay identical, the safest pattern is to generate only the changed region, then paste it onto the original in your own code. You pay for one edit at 7 cents at high quality, and the rest of the image is guaranteed unchanged.

If you only need to verify, the low-quality test costs 1 cent per image and is enough to see whether the edge behavior is acceptable for your type of photo.

Reading OpenAI's wording carefully

The sentence in OpenAI's guide is about GPT Image in general, read on 2026-10-08: the mask is used as guidance, and masking is prompt-based. It does not state a failure rate and neither does this post. The advice is simply to verify outside-mask pixels on the kinds of photo you edit, because a studio product shot on a plain background and a busy street scene can behave differently.

Sunburst for precision work

OpenAI positions Sunburst for workflows where editing precision matters most. If masked edits bleed on Flare, run the same edit on openai/gpt-image-2.5-sunburst; Sume prices both ids the same, so the test costs the same per image. Do not assume it fixes the bleed: judge it on your own photos.