Editing and Inpainting Prompts for GPT Image 2

TL;DR: GPT Image 2's edit endpoint does three things: edit an image, generate one from other images as reference, or edit a region with an uploaded mask. The mask is alpha-channel transparency, not black-and-white, and OpenAI admits it's followed loosely. Attach up to 16 images per call; two OpenAI documents disagree on whether input_fidelity does anything on this model.

What does GPT Image 2's edit endpoint actually let you do?

GPT Image 2 editing covers three distinct things, all through the same call. OpenAI's own image generation guide introduces the whole surface under one heading, "Edit Images", and lists exactly what it covers: "Edit existing images", "Generate new images using other images as a reference", and "Edit parts of an image by uploading an image and mask that identifies the areas to replace". Nothing in the request tells the API which of the three you mean. The API infers it from what you attach: one image and a text instruction is the first mode, several images with no mask is the second, and one image plus a mask is the third.

That third mode is what most people mean when they say "inpainting," and it's the one this article spends the most time on. But the first two are genuinely useful on their own, and skipping them is the most common reason someone reaches for a mask when a plain instruction would have worked. This piece stays on editing specifically; for GPT Image 2's text-rendering rules and its size and quality parameters in the generation direction, the companion piece is the free GPT Image 2 prompt generator.

How do you send an edit request, and which model name do you actually need?

Through images.edit, and by naming gpt-image-2 explicitly. That second part matters more than it looks. OpenAI's own OpenAPI specification lists the edit request's model field as accepting dall-e-2, gpt-image-1, gpt-image-1-mini, gpt-image-1.5, gpt-image-2, gpt-image-2-2026-04-21 or chatgpt-image-latest, and its documented default is gpt-image-1.5, not gpt-image-2. Omit model and you get the previous generation of the model family, silently.

curl -s -D >(grep -i x-request-id >&2) \
  -o >(jq -r '.data[0].b64_json' | base64 --decode > result.png) \
  -X POST "https://api.openai.com/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image[]=@lounge.png" \
  -F "prompt=A sunlit indoor lounge area with a pool containing a flamingo"

That call has no mask, so it runs the plain "edit an existing image" mode: the model treats the whole frame as open to change, guided entirely by the prompt. The prompt field accepts up to 32,000 characters on the GPT image models, and image accepts a single file or an array of up to 16, each a PNG, WebP or JPG under 50MB, per the same specification. size follows the same constraint-validated rules as generation, not a fixed enum, and an edit that requests a size outside them fails the same way a generation call does, which is covered in full in why your image came out the wrong size.

Do you need a mask, and what must it look like?

No, a mask is one option among the three modes above, not a requirement. When you do use one, it has to be exact. OpenAI's guide states the rule under "Mask requirements": "The image to edit and mask must be of the same format and size (less than 50MB in size). The mask image must also contain an alpha channel." A grayscale PNG with no transparency data fails validation before the model ever sees it, which is the single most common reason a first attempt at masked editing throws an error rather than a bad result.

The polarity is worth stating precisely, because it is easy to assume GPT Image works the way Stability's or FLUX's black-and-white masks do. It does not. OpenAI's OpenAPI schema defines the field this way: mask is "An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where image should be edited." The signal is transparency, not a grayscale value. Paint a mask as opaque-everywhere-except-the-hole, not as black-and-white, or the region you meant to protect is the one that gets rewritten.

If there are multiple images in the request, the mask only ever applies to the first one. OpenAI's guide states it plainly: "If you provide multiple input images, the mask will be applied to the first image." A mask attached alongside a five-image compositing call does nothing to images two through five.

Does GPT Image 2 follow a mask exactly?

No, and OpenAI is direct about the limit rather than leaving it to be discovered. Its guide states: "Masking with GPT Image is entirely prompt-based. The model uses the mask as guidance, but may not follow its exact shape with complete precision." Treat a mask as a strong hint about where the model should work, not a hard selection the way a lasso tool in an image editor would be. If a region has to stay inside an exact boundary, plan for a follow-up pass, or finish the edge in a design tool afterward.

Edit the attached image using the mask. Fill the masked region with a
copper teapot on the same counter, matching the existing lighting and
shadow direction. Do not add a rim or edge line where the mask boundary
was; blend the new object naturally into the surrounding scene.

That last sentence is doing real work. Because the mask boundary is a guide rather than a hard edge, naming the failure mode you want to avoid, a visible seam where the mask ended, gives the model something concrete to avoid rather than leaving it to guess.

What happens when you edit with no mask at all?

The model treats the request as an instruction over the whole frame, and the constraint work moves entirely into the prompt. This is the plain edit-an-existing-image mode from the top of this article, and OpenAI's cookbook shows it used for jobs that have nothing to do with painting a specific region: style transfer, object removal, lighting changes, and compositing a person into a new scene.

result = client.images.edit(
    model="gpt-image-2",
    image=[open("man_with_blue_hat.png", "rb")],
    input_fidelity="high",
    prompt="Remove the flower from man's hand. Do not change anything else.",
    size="1024x1536",
    quality="medium",
)

That prompt pattern, name the one change, then say what to leave alone, is the cookbook's own recommended structure for a no-mask edit: "For edits, use “change only X” + “keep everything else the same,” and repeat the preserve list on each iteration to reduce drift." Say what should change first, then spend the rest of the sentence on everything that should not. There is no dedicated exclusion field to lean on instead: gpt-image-2 has no negative_prompt parameter, the same gap mapped across every image model that does and doesn't have one, so every "do not add X" has to live inside this same sentence.

What does input_fidelity actually control, and should you set it?

This is the one place the two primary OpenAI documents checked for this article disagree, and it is worth stating plainly rather than picking a side. The image generation guide is unambiguous: "The input_fidelity parameter controls how strongly a model preserves details from input images during edits and reference-image workflows. For gpt-image-2, omit this parameter; the API doesn’t allow changing it because the model processes every image input at high fidelity automatically."

The GPT Image Generation Models Prompting Guide, OpenAI's own cookbook, does the opposite. Its worked examples set input_fidelity="high" directly on gpt-image-2 edit calls, several times, and its own advice text reads: "When available, higher input fidelity helps maintain likeness during larger scene edits." The OpenAPI specification's field description adds a third data point that does not resolve the other two. Its exact wording: "This parameter is only supported for gpt-image-1 and gpt-image-1.5 and later models, unsupported for gpt-image-1-mini. Supports high and low. Defaults to low." Read literally, the phrase "and later models" could be read as including gpt-image-2.

How do you edit with more than one reference image?

By passing an array to image, up to 16 files, and letting the prompt describe how they relate to each other. This is the endpoint's second documented mode, generating a new image from other images purely as reference, and OpenAI's own example is a gift basket assembled from four separately photographed products:

const images = await Promise.all(
  imageFiles.map(async (file) =>
    await toFile(fs.createReadStream(file), null, { type: "image/png" })
  )
);
const response = await client.images.edit({
  model: "gpt-image-2",
  image: images,
  prompt:
    "Generate a photorealistic image of a gift basket on a white background labeled 'Relax & Unwind' with a ribbon and handwriting-like font, containing all the items in the reference pictures.",
});

The same shape covers compositing a second subject into an existing scene. The cookbook's own worked example attaches two images, a finished portrait and a photo of a dog, and describes the placement in one sentence: "Place the dog from the second image into the setting of image 1, right next to the woman, use the same style of lighting, composition and background. Do not change anything else." Swap the nouns for your own two subjects and the pattern holds: name what moves, name where it goes, then close with the same preserve clause used everywhere else on this page. It is a plain-language stand-in for the mask you would otherwise have had to draw.

Six edit patterns that actually hold up

Each of these is a real workflow from OpenAI's own cookbook, condensed to the reusable shape.

Style transfer. Keep a reference image's palette and texture, change the subject. "Use the same style from the input image and generate a man riding a motorcycle on a white background."

Object removal. Name only what leaves. "Remove the flower from man's hand. Do not change anything else."

Sketch to photograph. Turn a rough sketch into a photorealistic render while keeping its composition. "Choose realistic materials and lighting consistent with the sketch intent. Do not add new elements or text."

Product extraction. Isolate a subject on a transparent background for reuse elsewhere. Pair background="transparent" with output_format="png" or "webp", since jpeg does not support transparency, and describe the subject as isolated with "no scenery, solid backdrop, checkerboard, or unwanted shadows."

Lighting change. Alter mood without touching layout. The cookbook's own one-line prompt for this: "Make it look like a winter evening with snowfall." Nothing else in the sentence, because nothing else needs to change.

Interior object swap. Replace one furnished element while preserving the camera. The cookbook names the goal directly: "The goal is surgical realism: swap a single object while preserving camera angle, lighting, shadows, and surrounding context so the edit looks like a real photograph, not a redesign." Its own prompt closes the edit with the same preserve line used throughout this article: "Keep all other aspects of the image unchanged. Photorealistic contact shadows and fabric texture."

How do you fix one detail without losing everything else?

By writing a single-change follow-up rather than a fresh prompt, and by repeating the preserve list every time. A fresh prompt regenerates the entire image and throws away the ninety percent that was already right. OpenAI's cookbook names this directly as the pattern that held up across "generation, edits, infographics, ads, human images, UI mockups, and compositing workflows" in its own testing.

Edit the attached image. Replace only the mug with a small potted plant.
Preserve the person, desk layout, lighting, colors, crop, and every
other detail exactly. Do not add text or logos.

That example comes from OpenAI's own ChatGPT product documentation, word for word, and it is worth using as a template precisely because it names four separate things to preserve rather than one vague catch-all phrase. The more specific the preserve list, the less the model has to guess about what counts as everything else.

Can you edit inside a conversation instead of one-shot calls?

Yes, on the Responses API, and it behaves differently from images.edit in a way worth knowing before you pick a surface. OpenAI's guide describes the difference directly: compared to the Image API, the Responses API's image generation tool adds "Multi-turn editing: Iteratively make high fidelity edits to images with prompting" and "Flexible inputs: Accept image File IDs as input images, not just bytes". You keep an image in context across turns using previous_response_id or by carrying the image generation call forward, and an optional action parameter decides what happens next. The guide states it plainly: "The optional action parameter controls this behavior: keep action: "auto" to let the model decide, set action: "generate" to always create a new image, or set action: "edit" to force editing when an image is in context."

const response = await openai.responses.create({
  model: "gpt-5.6",
  input: "Make it look like a winter evening with snowfall",
  previous_response_id: previousResponse.id,
  tools: [{ type: "image_generation", action: "edit" }],
});

action: "edit" is the one worth remembering. Without it, a prompt like "make it snowier" can be read as a request for an entirely new image rather than a change to the one already in context, and on a multi-turn thread that ambiguity is exactly what breaks a series that is supposed to look consistent shot to shot, a problem this site covers on its own in keeping one visual style across a whole series.

API edit vs the ChatGPT app: which surface should you use?

Whichever one matches how precisely you need to name the region. The app gives you a UI-level selection, not a real mask. OpenAI's own ChatGPT documentation states: "You can also select a specific area of an image and describe the change for that area." Separately, for gathering notes across several images at once, it adds: "Select Multi-select to choose the images you want to include, then send your comments and any additional editing instructions in the same chat."

If you're testing a prompt template you plan to reuse programmatically, build and check it against the Images API, where the request shape is exactly what you specify. The app is faster for a one-off touch-up where drawing a real mask is more setup than the edit is worth.

What does OpenAI itself say GPT Image 2 still gets wrong?

Two named limits, under its own "Limitations" heading, and both matter directly for editing work. "Consistency: While capable of producing consistent imagery, the model may occasionally struggle to maintain visual consistency for recurring characters or brand elements across multiple generations." And: "Composition Control: Despite improved instruction following, the model may have difficulty placing elements precisely in structured or layout-sensitive compositions."

Read together with the mask-precision caveat above, the honest summary is that GPT Image 2 is a strong editor that still treats every instruction as a suggestion rather than a constraint. That is exactly why the single-change, name-the-preserve-list pattern earns its place in every example on this page: it is the discipline that keeps a suggestion-following model from wandering, one small request at a time. Prompt Architects does not run the edit itself; it generates, structures and stores the instruction and the preserve list as a reusable template, so the same disciplined phrasing survives from the first edit to the fortieth.

A checklist before you submit an edit request

1. Did you set model="gpt-image-2" explicitly? The documented default is gpt-image-1.5.
2. If you're using a mask, does it carry a real alpha channel, and is transparency the signal (not black-and-white)?
3. Is the mask the same format and size as the source image, and under 50MB?
4. If multiple images are attached, does your mask logic account for it only applying to the first one?
5. For a no-mask edit, does the prompt name the one change first, then list everything to preserve?
6. Have you decided on input_fidelity, aware that OpenAI's own docs disagree about what it does on this model?
7. Are you on the surface that matches the precision you need: Images API for a repeatable template, the app for a one-off touch-up?

Seven checks, most of them one line each. On identity-sensitive or brand-sensitive edits they are the difference between a first-pass result and a fourth re-run, and on this model, per OpenAI's own limitations list, a fourth re-run is sometimes exactly what a "recurring character" job needs.