How to Build a Practical Image Editing Workflow with GPT Image 2

When an image-editing feature moves from a demo into a real product, the hard part is not only generating a good image once. It is building a repeatable workflow: accept an input image, preserve the parts the user cares about, change only what the prompt describes, and handle failures without losing the original context.

This guide walks through a practical way to use the Ace Data Cloud OpenAI Images Edits API for that kind of workflow. The examples are intentionally close to the documented contract: the endpoint is https://api.acedata.cloud/openai/images/edits, the common fields are model, image, prompt, size, n, response_format, optional mask, and optional callback_url.

What you can do

The editing API is useful when you already have a source image and want to transform it without starting from an empty canvas. A typical builder workflow might include:

• Changing a product color while keeping the camera angle, composition, and shadow intact.
• Replacing a background for ecommerce or social preview images.
• Using several reference images to guide a more controlled edit.
• Applying a local mask so that only a specific region is allowed to change.
• Switching long-running edits to asynchronous callbacks instead of blocking a request.

The documented model options include gpt-image-2, gpt-image-2:reverse, gpt-image-2:official, gpt-image-2.5-flare, gpt-image-2.5-flare:official, gpt-image-2.5-sunburst, and gpt-image-2.5-sunburst:official. In practice, a good default is to start with gpt-image-2, then choose a :official variant when you need the official multipart contract, such as mask-based editing.

How it works

There are two main input styles. If the source image is already hosted, send JSON with image as a URL. If the image is local, send multipart/form-data and upload the file with image=@input.png. JSON requests can pass image as a single URL or as an array of up to 16 URLs. Multipart requests can also pass multiple image file fields.

The prompt should describe both the desired change and what must remain unchanged. This matters because image editing is not only about adding new pixels; it is also about protecting composition, lighting, object identity, and canvas shape.

Start with URL-based editing

For many web applications, the simplest version is URL input. Your backend receives an image URL, builds a concise edit prompt, and calls the edits endpoint. This is close to the documented example:

curl https://api.acedata.cloud/openai/images/edits   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-image-2",
    "image": "https://cdn.acedata.cloud/assets/examples/gpt-image/d56455e2-e7f7-4bcd-b935-475b0a1e0948_0-18240dc44b9c.png",
    "prompt": "Keep the mug, tabletop, camera angle, portrait layout, and soft shadow unchanged. Change only the mug color from white to vivid orange and the pale cream background to solid dark navy blue. No text and no logo.",
    "size": "1024x1536"
  }'

A successful synchronous response includes success, task_id, trace_id, created, model, data, and usage. The generated image URL is returned inside data[0].url. Keep trace_id in your logs; the documentation recommends providing it when reporting issues, but not providing the API key.

Use multipart when users upload local files

If your app accepts uploads, multipart is the right shape. This avoids forcing the user to host the file first:

curl https://api.acedata.cloud/openai/images/edits   -H "Authorization: Bearer YOUR_API_KEY"   -F "model=gpt-image-2"   -F "image=@input.png"   -F "prompt=Replace the background with a bright modern studio"

This pattern is straightforward to put behind a form upload. Store the original file, send the edit request, and persist both the original and edited URLs so a user can compare results or retry with a tighter prompt.

Constrain edits with a mask

When you need local editing, use mask with an official model such as gpt-image-2:official. The mask must be a PNG with an Alpha channel, must not exceed 4MB, and must have exactly the same dimensions as the first image. Transparent pixels with Alpha 0 mark the editable area; non-transparent pixels are retained.

from PIL import Image, ImageDraw

source = Image.open("input.png").convert("RGBA")
mask = Image.new("RGBA", source.size, (0, 0, 0, 255))
draw = ImageDraw.Draw(mask)
width, height = source.size
draw.rectangle(
    (width // 4, height // 4, width * 3 // 4, height * 3 // 4),
    fill=(0, 0, 0, 0),
)
mask.save("mask.png")

Then upload the original and mask in the same multipart request:

curl https://api.acedata.cloud/openai/images/edits   -H "Authorization: Bearer YOUR_API_KEY"   -F "model=gpt-image-2:official"   -F "image=@input.png"   -F "mask=@mask.png"   -F "prompt=Keep the composition, lighting, and all objects outside the transparent mask unchanged. Inside the masked area, replace the empty tabletop with a small blue ceramic vase."

Do not combine a URL original image with a local mask file. The documented mask workflow uploads image=@input.png and mask=@mask.png separately in the same multipart request.

Size, callbacks, and failure handling

The size field can be auto or a compliant WIDTHxHEIGHT. Width and height must be multiples of 16, the longer side must not exceed 3840, total pixels must be between 655,360 and 8,294,400, and the aspect ratio must not exceed 3:1. The n field supports 1–10, but only 1 is supported when response_format=b64_json.

For long-running jobs, add a callback URL:

{
  "callback_url": "https://example.com/webhooks/images"
}

The asynchronous 200 response is {"task_id":"..."}, and the final result is delivered through the callback when complete. For errors, check the basics first: 400 usually points to image format, quantity, parameter combinations, size format, or mask validity; 401 points to the API key and Bearer header; 429 indicates request frequency; and 504 is a signal to switch to asynchronous callbacks.

A small production checklist

• Log task_id and trace_id for every edit.
• Validate image count before sending requests, especially when users attach multiple references.
• For mask workflows, verify PNG Alpha, file size, and dimensions before calling the API.
• Make prompts explicit about what should remain unchanged.
• Use callbacks for requests that should not block a web request lifecycle.

The useful mental model is simple: treat image editing as a controlled transformation, not a one-off generation. Preserve what matters, constrain what should change, and keep enough request metadata to debug issues later. For the complete field list and examples, read the Ace Data Cloud OpenAI Images Edits API guide.