How can developers edit only a masked area with the GPT Image API while preserving the rest?

What a mask does and does not promise

OpenAI documents image edits as modifying existing images, including editing parts of an image with an uploaded image and mask that identifies areas to replace. The mask is an input to the edit process. It is not an API promise that every unmasked output pixel will equal the corresponding input pixel. OpenAI image edit guide

This distinction matters because the model must synthesize a coherent image. It may adjust nearby lighting, texture, shadows, edge detail, or compression-like raster detail when it produces its result. A more restrictive prompt can improve the candidate, but cannot turn a generative output into an immutable-layer operation.

The practical conclusion is simple: use generation for the editable region and ordinary image processing for the protected region.

Alpha semantics and valid edit inputs

For the Image API masking workflow, make an RGBA mask in which the transparent area is the area you want the model to replace. The opaque area is the surrounding context that should remain intact in the model's candidate. Think of this as an API-specific export convention, not as the internal representation of your editor selection.

Maintain a separate logical selection in your application, for example editable equals one inside the user-selected area and zero elsewhere. Produce the API mask from that selection at request time. This prevents a common inversion bug, where a UI mask that uses white for selected pixels is uploaded without converting its meaning to alpha.

The current guide requires the image and mask to have the same format and pixel size, under the documented 50 MB limit, and requires the mask to contain an alpha channel. A PNG image plus a PNG mask is the least surprising choice because PNG preserves alpha. Check dimensions after decoding the files, not merely their CSS display dimensions or filenames. OpenAI mask requirements

Treat partially transparent pixels as a boundary instruction, not a calibrated fractional edit amount. Anti-aliased edges can be useful, but they also make it unclear which side of the boundary should count as protected. Keep a crisp logical selection for validation, then make any feathered transition band explicit in the final blend mask.

Do not confuse the edit mask with background set to transparent. The former tells the edit workflow where to replace content. The latter requests transparency in the generated output where a supported model and output format allow it. For gpt-image-2, transparent output is documented as preview and requires PNG or WebP, not JPEG. OpenAI output customization

A preservation-first editing pipeline

flowchart LR
    A[Original image] --> B[Logical user selection]
    B --> C[Crop selection plus context padding]
    A --> C
    C --> D[Export same-grid RGBA image and API mask]
    D --> E[GPT Image edit candidate]
    E --> F[Validate dimensions and inspect candidate]
    B --> G[Final blend mask]
    A --> H[Untouched original canvas]
    F --> I[Take only the candidate ROI]
    G --> I
    I --> J[Deterministic local composite]
    H --> J
    J --> K[Outside-mask pixel-difference gate]
    K --> L[Accept, retry, or send to review]

This diagram is also a useful implementation boundary. Everything left of the API call prepares a valid model input. Everything right of it is conventional, testable image processing that your application owns.

Prepare a padded crop

Send the model the smallest useful crop, not necessarily the tightest rectangle. A cushion recolor needs the cushion plus enough sofa, lighting, and shadow context for a credible replacement. A crop that ends on the object boundary often creates an edge mismatch because the model cannot see how material, shade, or perspective should continue.

Use two regions:

1. The final editable region is the area you allow to change in the delivered image. This becomes the compositor's blend mask.
2. The generation crop is that region expanded by context padding. It gives the model room to understand the scene, but its padding is never copied to the final output.

The padding amount is a product choice, not a universal number. It should cover the visual dependency around the edit, such as a cast shadow, a fabric seam, or a reflection. Increase it when candidates have edge discontinuities. Decrease it when unrelated items within the crop begin to drift. Record the crop rectangle and padding in the edit job so a failure can be reproduced.

Keep the coordinate system stable

The final compositor can only paste safely when the candidate uses the same pixel grid as the input crop. Choose a requested output size deliberately instead of allowing an automatic size selection when coordinates must line up. gpt-image-2 accepts flexible resolutions subject to documented constraints, including dimensions in 16-pixel increments, an edge limit of 3840 pixels, a maximum 3:1 aspect ratio, and a bounded total pixel count. OpenAI size constraints

If a crop does not meet those constraints, expand it with context or neutral padding before the request, then crop the generated candidate back to the original crop rectangle. Do not rescale a returned candidate to force it to fit. Resampling makes an apparently exact outer-pixel test meaningless and can create color halos at the pasted edge.

Write a narrow prompt

Describe the requested change, the object identity, and the visual properties that must survive inside the selection. Put preservation language in the prompt, but view it as candidate guidance rather than enforcement.

For the cushion example, a useful prompt is:

Edit only the selected orange cushions. Change their fabric color to a muted forest green.
Keep each cushion's shape, seams, folds, position, scale, material texture, highlights,
and cast shadows consistent with the input. Do not add, remove, crop, or rearrange objects.

This prompt says what should change and which in-region attributes matter. It does not need a long inventory of every object outside the selection because the mask and final compositor already provide stronger spatial protection. OpenAI's prompting guide recommends concrete details and maintainable prompt structure over clever syntax. OpenAI GPT Image prompting guide

Controls that help but do not change the contract

gpt-image-2 processes every input image at high fidelity automatically. The current guide says to omit input_fidelity for that model because the API does not allow changing it. Do not copy an input_fidelity setting from an older example into a gpt-image-2 request. OpenAI image input fidelity

The quality setting offers low, medium, high, and auto. The guide describes low as the fast option for drafts and recommends moving to medium or high for final assets. Use low quality to check that crop, alpha direction, and prompt scope are correct. Use the quality your evaluation set supports for final candidates. OpenAI quality options

Higher quality and high-fidelity input can improve the visual candidate, but neither one protects unmasked pixels after you accept the entire returned raster. Their role is quality selection, not preservation enforcement. For latency-sensitive products, start with a cheap diagnostic request only if the image grid and crop logic match the final workflow. Otherwise, a draft can hide the resolution or seam issue that affects production.

Composite the generated patch over the original

The final image should be calculated from the source image and a candidate, not obtained by merely saving the candidate. Let O be the original crop, G the generated crop, and a the final blend alpha from zero to one. Per pixel, the composite is:

final = (1 - a) * O + a * G

Where a is zero, copy the original value directly. Where a is one, use the generated candidate. Intermediate values are reserved for a deliberate transition band. Work in a consistent RGBA representation and use a compositor that handles alpha correctly. If your image library supports premultiplied alpha internally, use it consistently rather than mixing premultiplied and straight-alpha buffers.

Pseudocode

# editable is our own binary user selection: 1 inside the allowed edit, 0 outside.
# api_mask is a separate RGBA export with transparent pixels where editable == 1.

roi = expand(bounding_box(editable), context_padding)
source_crop = crop(original_rgba, roi)
selection_crop = crop(editable, roi)

assert image_format(source_crop) == "png"
assert dimensions(source_crop) == dimensions(selection_crop)

api_mask = make_rgba_mask(
    transparent_where=(selection_crop == 1),
    opaque_elsewhere=True,
)

candidate = call_image_edit(
    model="gpt-image-2",
    image=encode_png(source_crop),
    mask=encode_png(api_mask),
    prompt=edit_prompt,
    size=dimensions(source_crop),       # Set only when that grid is supported.
    quality="high",                     # Chosen after evaluation, not as a guarantee.
)

assert dimensions(candidate) == dimensions(source_crop)

# Keep the feather inside the declared editable region. If a wider transition
# band is needed, include that band in the user-visible editable region first.
blend_alpha = feather_inside(selection_crop, radius=chosen_radius)
patched_crop = alpha_composite(source_crop, candidate, blend_alpha)

final = original_rgba.copy()
paste(final, patched_crop, roi)

protected = (editable == 0)
assert max_channel_difference(final, original_rgba, protected) == 0

The call syntax is intentionally pseudocode because SDK signatures can change. The documented Python Image API pattern is client.images.edit with model, image, mask, and prompt, with a base64-encoded image result. Verify any optional parameters against the current Image API reference before deploying.

Feathering without breaking the promise

A hard cut can make a green cushion look pasted in if the generated fabric no longer aligns exactly with the original antialiased border. Feathering is a normal remedy, but it changes the definition of outside. A feather that spills outside the original lasso blends generated pixels into a region the user may consider protected.

Choose one explicit policy:

• Keep the blend alpha zero outside the lasso. This maximizes strict protection, but may leave a visible seam.
• Add a small, visible transition band to the editable selection, then feather only within that expanded region. This gives the generator and compositor room to blend, but honestly declares the band editable.
• Use a hard edge where the boundary is naturally sharp, such as a product silhouette or a window frame.

For textured photos, convert both images to a consistent color-managed working space before blending. A seam may come from different color profiles, gamma handling, or premultiplied-alpha errors rather than a poor generated image. Preserve the original's metadata and apply deterministic metadata handling at export so reproducibility tests are not confused by changed timestamps or encoder settings.

A worked cushion recolor example

Hypothetical setup: A 1920 by 1306 interior image contains two orange cushions. The user selects the visible cushion shapes but not the sofa, table, or floor. The product requires that every pixel outside the selection remain unchanged in the delivered PNG.

1. Expand the combined selection by enough pixels to include nearby sofa fabric and the cushions' shadows. Export that crop and an RGBA API mask with the selection transparent and the rest opaque. Keep a separate binary copy of the user selection for later compositing.
2. Request a candidate with the narrow recolor prompt. Before accepting it, check that its decoded dimensions exactly equal the submitted crop dimensions. If the grid differs, reject it for this workflow rather than stretching it.
3. Inspect the candidate's cushion shape, seams, and green color. If it is not acceptable, retry with a revised prompt or crop. The candidate may have changed the sofa in its outer padding, and that is acceptable because no padding pixels will be pasted.
4. Copy the candidate only through the final blend mask onto the source image. Compute the channel-wise difference outside the final mask. A maximum difference of zero passes the preservation gate. A nonzero value means a bug in crop coordinates, mask polarity, blending, or export.

The takeaway is that the model is judged on the edited cushions, while the application enforces the exactness requirement for the sofa, table, floor, and every other protected pixel.

Candidate selection and regression tests

Treat an image edit as a candidate-generation step with separate checks for visual success and protected-pixel integrity.

Maintain a small golden set before changing a prompt template, model, crop heuristic, image library, or output encoder. Include smooth gradients, noisy texture, sharp product edges, shadows crossing the selection boundary, repeated objects, text near the selection, and an object partly outside the frame. Store the original, logical selection, API mask, crop rectangle, prompt template version, request settings, candidate, final output, and test result. Those artifacts make a regression attributable.

Set a non-negotiable gate of zero protected-pixel change for workflows that promise exact preservation. Set separate, context-specific acceptance thresholds for edit quality, such as whether a product label remains legible or a cushion's silhouette remains plausible. Do not reduce the protected-pixel gate to compensate for a poor edit. Retry or route the task to review instead.

Debugging checklist

• Confirm that the uploaded mask really contains alpha after your image encoder writes it. A black-and-white bitmap without alpha is not the documented mask format.
• Render the logical selection, API alpha mask, crop rectangle, and final blend mask as separate debug overlays. They should not be assumed to be the same raster.
• Verify image and mask format and dimensions after encoding. The documented Image API requirement is same format and size, not merely matching aspect ratio.
• Log the requested output size and decoded candidate size. Reject an unexpected grid before compositing.
• Test one obvious edit with a rectangle before testing a complex brush or segmentation mask. This isolates alpha inversion from object-selection errors.
• First save the raw candidate and calculate its drift outside the selection. Then save the composited final and calculate its protected-pixel difference. These are different diagnostics.
• If a result contains blank or transparent-looking content, inspect both the API mask polarity and any output-background setting. Do not infer that output transparency and edit-mask transparency mean the same thing.
• If a seam appears, inspect crop padding, selection coverage, color profile conversion, alpha mode, and whether your feather extends outside the declared editable band.
• If the candidate changes the wrong object within the mask, tighten object identity and desired properties in the prompt, or split a large selection into separate edits.
• If repeat edits differ, keep the accepted candidate and audit record. Do not assume reproducibility controls that the current image-endpoint documentation does not explicitly provide for the selected model.

Limits and viable alternatives

Local compositing makes the protected area exact, but it cannot make a model preserve every detail inside the selected area. A requested recolor may still alter fabric weave, a button, a shadow, or a partially selected object. Make the editable region only as large as the product can truthfully permit, then assess the generated content within it.

Use a deterministic editor instead of a generative model when the requested operation is already deterministic. Examples include changing a known flat fill, applying a fixed LUT, compositing a supplied product asset, rendering approved text, or resizing and cropping. This is both faster and more reliable when the requirement is exact geometry or regulated artwork.

For high-value imagery, give the user a review step with the original, selection overlay, raw candidate, final composite, and a difference overlay. Do not present an AI edit as proof of a factual visual condition, and ensure that the application has rights and appropriate consent for the images it submits and modifies.