Configure image-editing workflows, including inpainting, mask-based edits, and prompt-driven modifications

Editing uses a different endpoint from generation, a different content type, and one parameter whose semantics are the reverse of most people's intuition: in a mask, the transparent pixels mark what gets edited. Getting that backwards produces a plausible image with everything changed except the part you meant.

Why This Matters

The mask convention is inverted relative to intuition. "The mask parameter defines the area of the image that you want the model to edit, using fully transparent pixels (alpha of zero) in those areas." Transparent means edit here.

Editing is a different endpoint. /images/edits, with Content-Type: multipart/form-data — not the JSON generation call.

input_fidelity is what keeps the rest of the image intact. It "enables subtle edits to an image without changing unrelated areas", which is exactly the property an editing workflow needs — and mini does not support it.

Prerequisites

• The image models and their size rules from the generation objective.
• What an alpha channel is, and that JPEG has none.
• multipart/form-data as a file-upload content type.
• input_fidelity and its role in preserving style and faces.

Learning Objectives

By the end of this lesson you will be able to:

1. Call the edits endpoint with the correct content type and fields.
2. Construct a mask that edits the intended region.
3. Distinguish inpainting, variations, and prompt-driven edits.
4. Preserve unrelated areas with input_fidelity.
5. Apply the model, size, and format constraints that carry over from generation.

Building Blocks

The endpoint.

Headers: Content-Type: multipart/form-data and api-key. Fields are supplied as form parts — image[], prompt, model, mask, size, n, quality.

Model support. All current image models support editing: GPT-Image-2 ("improved editing performance with inpainting and variations"), GPT-Image-1.5, GPT-Image-1, and GPT-Image-1-Mini ("inpainting and variations with mask + prompt").

The mask.

input_fidelity. Controls "how much effort the model puts into matching the style and features, especially facial features, of input images". High "preserves faces more accurately than standard mode" and "enables subtle edits to an image without changing unrelated areas". Not supported by gpt-image-1-mini.

Carried-over constraints. quality (low/medium/high), output_format (png/jpeg, no WEBP), output_compression (JPEG only, 0–100, default 100), background: transparent (GPT-image-1 only, requires PNG), the size rules per family, base64 responses, and 5 images per minute default quota.

Deep Dive

The mask, and why it is inverted

The mask is a PNG the same size as the input image, and the region you want changed is marked by fully transparent pixels — alpha of zero.

The intuition most people bring is the opposite: paint the area you care about in white or black, leaving the rest clear. Under that convention the model edits everything except the intended region, and because the output is a coherent image rather than an error, the mistake is not obvious from the response — the subject changes and the background stays, when you wanted the reverse.

Two structural consequences follow.

The mask must carry an alpha channel, which is why it must be a PNG. A JPEG mask cannot express the instruction at all.

Dimensions must match exactly. A mask drawn at a different scale, or exported after a resize, targets the wrong pixels. Since the source image must also be under 50 MB and PNG or JPG, an application that accepts user uploads needs a normalisation step — check size, convert format, and generate the mask against the normalised image, not the original.

Three kinds of edit, and choosing between them

The distinction is whether a mask is supplied and how much of the image is in scope.

Inpainting supplies a mask, so only the transparent region is regenerated. This is the highest-control option and the right answer whenever the requirement names a specific area — replace the object on the table, remove the blemish, change the sign text. The prompt should describe what belongs in that region, not restate the whole scene, because everything outside the mask is fixed.

Variations supply no mask: the model reinterprets the image as a whole, producing alternative takes on the same subject. Useful for exploring, useless when a specific region must change and the rest must not.

Prompt-driven modification also supplies no mask but directs the change through the prompt — restyle, relight, change the palette. Scope is whatever the prompt implies, and the lever for restraint is input_fidelity: set high, it "enables subtle edits to an image without changing unrelated areas".

A useful rule: if you can draw the region, mask it. A mask is a precise, deterministic instruction; a prompt asking the model to change only one thing is a request it may interpret broadly.

Preserving what should not change

The characteristic editing failure is collateral change — the requested edit lands, and the face, the branding, or the background shifts slightly too.

input_fidelity is the documented control. It governs "how much effort the model puts into matching the style and features, especially facial features, of input images", preserves faces more accurately at high, and enables subtle edits without changing unrelated areas.

Two consequences for design.

Mini is excluded from fidelity-sensitive editing, since input_fidelity is not supported by gpt-image-1-mini — and mini also defaults to medium quality where the others default to high, so a cost comparison that ignores both is misleading.

There is a trade-off. Higher fidelity to the input means less freedom to follow a divergent prompt. A large stylistic change with fidelity pinned high will be resisted; the combination to reach for is a mask plus high fidelity, where the mask grants freedom exactly where you want it and fidelity protects everything else.

What carries over from generation

Editing inherits the generation constraints, and forgetting them is a common source of failed calls.

Size rules by family. The gpt-image-1 series accepts 1024x1024, 1024x1536, 1536x1024; GPT-Image-2 accepts arbitrary resolutions under its four simultaneous constraints — edges multiples of 16 px, long edge to 3,840 px, ratio to 3:1, pixels 655,360–8,294,400.

Format rules. output_format is png or jpeg with WEBP unsupported; output_compression (0–100, default 100) is JPEG only; background: transparent requires PNG and is GPT-image-1 only — which matters for editing a product shot into a transparent cutout.

Response and throughput. The GPT-image-1 series always returns base64, and default quota is 5 images per minute — a bulk retouching workflow will hit that first.

Worked Examples

Example 1 — the wrong half changed. A workflow masks a product on a table intending to replace it. The output keeps the product and changes the table and background.

The mask is inverted. Transparent pixels — alpha of zero — mark the area to edit, so the product region must be transparent and the surroundings opaque. Note this produced a valid image rather than an error, which is why the assertion belongs in the workflow.

Example 2 — a blemish removal that alters the face. Retouching removes a mark but subtly changes facial features.

Raise input_fidelity, which controls matching of "style and features, especially facial features" and "enables subtle edits without changing unrelated areas". Combine it with a tight mask covering only the blemish. If the workflow is on gpt-image-1-mini, move off it — mini does not support input_fidelity.

Example 3 — a mask that will not apply. A user uploads a 60 MB TIFF; the application resizes it for display and generates a mask from the resized version.

Two failures. The input must be under 50 MB and PNG or JPG, so the TIFF needs converting. And the mask must have the same dimensions as the input image — a mask built from the display-sized copy does not match the submitted original. Normalise first, then mask against the normalised image.

Visual Explanations

Mask semantics:

Choosing the edit type:

Common Mistakes

Inverting the mask. Transparent = edit; the error is silent.

Using a JPEG mask. It has no alpha channel; the mask must be PNG.

Mask dimensions not matching the input image.

Submitting an image of 50 MB or more, or an unsupported format.

Sending JSON to the edits endpoint. It takes multipart/form-data.

Describing the whole scene in an inpainting prompt. Describe the masked region.

Editing on mini where fidelity matters. input_fidelity is unsupported there.

Expecting high fidelity and a large stylistic change together. Use a mask to grant freedom locally.

Forgetting the generation constraints carry over. Sizes, formats, base64, 5 images/minute.

Practice Exercises

1. State the four mask and input rules.
2. Which pixels are edited, and why does an inverted mask not produce an error?
3. Distinguish inpainting, variations, and prompt-driven edits.
4. Which parameter preserves unrelated areas, and which model lacks it?
5. A user uploads a 60 MB TIFF. List every problem before an edit can run.

Summary & Concept Map

Editing runs through /images/edits with multipart/form-data, and every current image model supports inpainting and variations with mask plus prompt. The mask is the crux: a PNG of identical dimensions whose fully transparent pixels (alpha zero) mark the region to edit — inverted, it silently regenerates the surroundings instead. Inputs must be under 50 MB in PNG or JPG. Choose inpainting whenever the region can be drawn, variations for alternatives, and prompt-driven edits for global change restrained by input_fidelity, which preserves style and facial features and enables edits without changing unrelated areas — and is unavailable on mini. All the generation constraints carry over: family size rules, output_compression on JPEG only, transparency on GPT-image-1 with PNG, base64 responses, and 5 images per minute.

Sources and freshness

Written against current Microsoft Learn documentation for the AI-103 skills measured (16 April 2026), reviewed 2026-08-20. Microsoft Learn controls every changing product contract — availability, preview status, quotas, limits, regional support, naming, and retirement dates all move independently of this lesson. Where a scenario turns on a specific number or a GA/preview boundary, confirm it against the product's own page before relying on it.