Masks, Input Fidelity, and the Mechanics of a Targeted Edit

Editing is generation with something to preserve

Generation starts from nothing and is judged on whether the result matches the prompt. Editing starts from an existing picture and is judged on two things at once: whether the change happened and whether everything else survived. That second criterion is what makes editing a genuinely different skill, and it is what the mask and input-fidelity controls exist to serve.

The Image Edit API modifies existing images based on text prompts you provide. It is generally available and supported for production use — worth stating, because several neighbouring features on this topic are still preview. The call resembles an image generation call, with one obvious addition: you supply an input image.

The first trap is the content type

An edit request is not JSON. The Image Edit API takes multipart form data, and this catches out almost everyone the first time, because every other call in the vicinity is a JSON body. In practice this means your fields arrive as form parts — the image file, the prompt, the model deployment name, the size, the count, the quality — rather than as keys in an object.

The input image itself must be under 50 MB and must be a PNG or JPG file. The endpoint lives under your resource's deployments path with an explicit API version, and a successful response returns the edited image in a b64_json field, the same base64-only contract that generation uses.

Get the content type wrong and you get an error that reads like a malformed request rather than a wrong-format request, which is why it is worth memorising as a fact rather than rediscovering as a bug.

What a mask is, and the inversion that trips people up

Without a mask, an edit instruction applies to the whole image and the model decides what to touch. A mask makes the intent explicit. The mask parameter takes the same kind of value as the image input, and it defines the area you want the model to edit using fully transparent pixels — alpha of zero — in those regions. The mask must be a PNG and must have the same dimensions as the input image.

Read that carefully, because the polarity is the opposite of most people's first guess. Transparency does not mean "leave this alone". Transparency marks the editable region. The opaque parts of the mask are the parts you are protecting. Every team that builds a masking UI gets this backwards at least once, and the symptom is memorable: the model faithfully edits precisely the area you meant to preserve.

The same-dimensions rule is equally unforgiving. A mask authored against a resized preview will not align with a full-resolution original, so any interface that lets a user paint a mask on a scaled-down view has to scale the mask back up before sending it. A mask that is off by a few pixels produces edits that bleed at the boundary, which reads as poor model quality when it is really a coordinate bug.

This mask-and-prompt combination is what supports inpainting — changing a specific area while the rest of the frame holds — and the models in the GPT-Image family support inpainting and variations alongside it.

Input fidelity: how hard the model tries to keep the original

The second control is subtler and more powerful. The input fidelity parameter governs how much effort the model puts into matching the style and features — especially facial features — of the input images.

The purpose is stated plainly: it lets you make subtle edits without changing unrelated areas. With high input fidelity, faces are preserved more accurately than in standard mode. That is the difference between an edit and a re-imagining. Change the background behind a person at standard fidelity and you may get a subtly different person; at high fidelity you get the same person against a new background.

One restriction is decisive for model selection: input fidelity is not supported by the mini model. If your scenario involves people and your requirement is that they stay recognisably themselves, that restriction disqualifies mini before you evaluate anything else about it. Mini's whole positioning — fast, cheap, bulk, no dedicated face preservation — is consistent with this; it is built for general creative imagery, not for retouching portraits.

Streaming and transparency carry over

The edit path shares two conveniences with generation. Streaming returns partial images as they are produced, controlled by a partial-images setting, which improves perceived latency in an interactive editor where a user is watching a change take shape. And transparency still requires the background setting and PNG output together — one without the other quietly gives you an opaque result.

Common mistakes

Sending JSON to an endpoint that expects multipart form data.

Inverting the mask, so the model edits exactly what you wanted preserved.

Authoring a mask against a resized preview and never scaling it back, producing edits that drift at the edges.

Choosing mini for a face-preservation scenario, where input fidelity — the parameter that would have solved the problem — is unavailable.

And reaching for a mask when a plain prompt would do. Masks add precision and a whole class of alignment bugs; use them when the change genuinely must be confined.