GPT Image API: How can I reliably edit only the masked/selected area while preserving everything else?

[davidsou.fer]

Hi everyone,

I’m currently experimenting with the OpenAI Images API and GPT Image 2, specifically the image editing/inpainting functionality using masks.

My goal is to build an application where a user can select a specific area of an already generated image and request a localized modification.

For example:

• The user selects one or more cushions in an interior design image.
• The user asks: “Change the orange cushions to green.”
• Only the selected cushions should be modified.
• Everything outside the selection should remain unchanged.
• Ideally, the selected object itself should also remain as intact as possible, with only the requested property (e.g. color/texture) being changed.

I’m currently testing this using the images.edit API with a PNG mask containing an alpha channel.

My basic implementation looks like this:

from openai import OpenAI
import base64
import os

client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

result = client.images.edit(
    model="gpt-image-2",
    image=open("base.png", "rb"),
    mask=open("mask-api.png", "rb"),
    prompt="Change the texture of the orange cushions to green."
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)

with open("composition-image.png", "wb") as f:
    f.write(image_bytes)

The mask has the same dimensions as the original image and uses transparency to indicate the editable area.

However, I’m getting some unexpected results.

Test results

In one of my tests, I selected a specific region containing the orange cushions.

The expected behavior was:

Only the orange cushions inside the selected/masked area should be changed to green, while everything else should remain exactly as close as possible to the original image.

Instead, the generated image sometimes:

1. Changes parts of the image outside the masked area.
2. Changes objects that were not part of the requested edit.
3. Leaves parts of the masked area transparent/empty instead of preserving the original content.
4. Re-generates more of the selected region than necessary, even though I only requested a color/texture change.

I’ve also tried making the prompt more explicit, for example:

Only modify the orange cushions inside the editable area.

Change their fabric to green.

Do not modify any other object.
Keep the sofa, table, floor, walls, lighting, perspective, composition,
shadows and all other elements unchanged.

However, I still see changes outside the intended area.

base.png:

mask-api.png (I want to edit only de the selected tranparent area):

composition-image-2.png (result):

[_j]

The entire image must be regenerated as a new output with gpt-image models. You cannot have perfect preservation - and cannot avoid it being watermarked.

The mask is an image prompt, and the AI model acts on that prompt, but it has agency to do what it wants.

The best thing you can do is encourage recitation by:

• Constraining input image + mask to the exact output resolution also specified;
• Make that exact image sent one that is supported in the 16px increments;
• Understand the downsizing rules automatically applied to large or upscaling to undersized input images, and adapt both a custom resize strategy and an output resolution within the overlapping size capabilities (or double the output size vs the vision)
• Do not exceed 3:1 or 1:3 ratios, and better, keep the ratios constrained to within likely training, under 2:1.
• Avoid padding or unnecessary outfill hints in a mask, instead, trim up the input image by any excess to align the two dimensions within the 16px capability.
• Use quality:high for the finest resolution in having the AI create the most faithful output.

The patches of input images and the resizing internally done is limited to 1536 “token” equivalents, and is also at fixed size increments. My vision pricing calculator shows the mechanism of gpt-image-2:

You can let that resize algorithm do the heavy lifting in determining what the requested output size should be.

---

I have an app that goes beyond merely accepting the output: if the generated image aligns precisely, you can “draw” API output over the original image. Using the above techniques of limited input and output size to realize a match, an image can align over the original, but the prompt must not have any contrary instructions (such as “zoom out”).