This guide was prepared with AI assistance using the linked documentation. Code examples are illustrative; verify them against your environment and current API documentation before use.
Define what needs to change
A useful editing request identifies the source image, the desired change, and the parts that should remain consistent. For example, change a background color while retaining the product shape. Keep the original file available so you can compare the result.
For a one-off generation or edit, OpenAI's guide points to the Image API. For a conversational flow that refines an image over multiple turns, the Responses API supports an image-generation tool and image context.
Choose between generating and editing
The Responses image-generation tool can select an action automatically or use an explicit generate or edit action. An edit requires an image in context; forcing an edit without one returns an error. Verify model and tool support in the current guide before selecting an API.
A reference image can guide a new result. It doesn't guarantee pixel-perfect preservation, so tell reviewers exactly which details matter.
Use masks and markup carefully
A mask can indicate a region to edit. OpenAI notes that GPT Image uses the mask as guidance and may not follow its boundary exactly. Inspect edges, labels, and nearby details after generation.
The Image API's markup-guided edit flow uses a separate transparent annotation layer for supported models. The guide specifies matching dimensions and says not to combine markup with a mask. Check those requirements when you implement the selected flow.
Track the right artifacts
Store a reference to the input, prompt, model, output, and review decision according to your application's policies. Do not put a user's private source files into a public asset directory just because the final image may be published.
The following TypeScript shape is an illustrative internal record, not a provider response type.
type ImageReview = {
inputAssetId: string;
outputAssetId: string;
requestedChange: string;
status: "pending" | "approved" | "rejected";
reviewerNote?: string;
};Check the output before release
- Compare the output with the original at full size.
- Check product geometry, text, logos, and any masked boundary.
- Confirm the file format and dimensions required by the destination.
- Review usage rights and disclosure requirements for your actual context.
- Retain a way to replace or remove an output that fails review.
Handle partial images and errors
The provider documents streaming partial images for supported workflows. A preview can help someone see progress, but it isn't necessarily the final asset. Label it accordingly and only mark the job complete after the final output arrives.
Expose a failure state and a retry action. Retrying generation may create a different image and incur additional usage, so do not silently replace an approved asset.
Turn a requested edit into review criteria
Suppose a product team wants the background of a product photo changed while keeping the item itself recognizable. Before generating, record the original, the requested background, the intended display size, and the details the reviewer must compare. A small preview can hide a changed label or edge; inspect the output at the size people will actually use.
If using a mask, examine both inside and outside the marked area. The provider describes masks as guidance rather than a precise pixel guarantee. If using markup, keep the annotation as a separate transparent layer and check the current guide's input and dimension requirements. Don't flatten the markup into the original if the API requires a separate layer.
When an output fails, record what failed: for example, an altered label or an unwanted change outside the intended region. That note helps a reviewer decide whether another edit is appropriate. It is not proof that a subsequent generation will fix the issue.
Publish an approved asset deliberately
Give each output a stable asset identifier in your application, with a link to its source and approval record. A generated file should remain pending until the person responsible for the destination approves it. If you generate a replacement later, keep it distinct from the approved file until the new review is complete.
Before serving an asset, check dimensions, file type, compression, accessibility text, and the context in which it appears. The correct alternative text describes the image's role in the page; it doesn't need to repeat a nearby caption. Optimize delivery only after checking that the result still looks acceptable at the intended size.
A failed or interrupted generation needs a visible state and a route back to the original. Preview images are useful during generation, but don't label a preview as an approved final file. Keep retention and permission decisions for private inputs separate from the publication of a final image.
If the final image is destined for a public page, review it in that page rather than only in the generation tool. A crop, overlay, or small viewport can hide important details or make the result misleading. Check both the original and edited version at the intended dimensions, and confirm who owns the approval. Keep a reference to the prior approved asset so the team can restore it if a later edit is rejected.
Sources and further reading
Documentation reviewed November 9, 2026. Verify current model support, limits and pricing before implementation.