How to Build Reliable Image Editing Workflows with GPT Image 2

September 24, 2026

If your product needs image editing that can preserve composition while changing only the parts you describe, a plain text-to-image call is often too loose. A better pattern is to send the original image, a precise edit instruction, and—when needed—a mask that limits the editable area.

What you can do

The Ace Data Cloud OpenAI Images Edits endpoint lets you call GPT Image 2 / 2.5 image editing through a single API surface:

Edit an image from a URL with a JSON request.
Upload a local image with multipart/form-data.
Pass one image or multiple reference images; the GPT Image series supports up to 16 reference images.
Use a PNG mask with an Alpha channel for local edits when using multipart uploads.
Choose between url and b64_json response formats.
Use callback_url for longer running tasks.

How it works

The editing endpoint is POST https://api.acedata.cloud/openai/images/edits. For a URL-based edit, you send JSON with a model, an image URL, a prompt, and optionally a size. For local files, you use multipart/form-data with one or more image fields.

The most important habit is to write the prompt as an editing contract, not as a vague creative brief. Say what must change and what must remain unchanged: composition, camera angle, lighting, objects outside a masked area, or the first reference image's layout.

Start with a URL-based edit

A URL edit is the simplest way to automate product mockups, brand variants, social creative variants, or visual QA flows where the input image is already hosted.

curl https://api.acedata.cloud/openai/images/edits \
  -H "Authorization: Bearer $ACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "image": "https://platform2.cdn.acedata.cloud/gpt-image/d56455e2-e7f7-4bcd-b935-475b0a1e0948_0.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 fields such as success, task_id, trace_id, created, model, data, and usage. The edited image URL is returned at data[0].url.

Use multipart uploads for local files

When the source image lives on disk, upload it directly. This is also the route you need when you want to use a local mask file.

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

For JSON requests, image can be a single URL or an array of URLs. For multipart requests, send one or more image file fields. If you are using mask, keep the original image and mask in the same multipart request; do not mix a URL original image with a local mask file.

Constrain edits with a mask

Masks are useful when you need predictable local edits: replacing an object on a table, changing a sign, or modifying a region while preserving the rest of the frame. 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 mark content that should be preserved.

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 send the original image and mask together:

curl https://api.acedata.cloud/openai/images/edits \
  -H "Authorization: Bearer $ACE_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."

Pick the right model and parameters

The documented model choices 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. The flare variants focus on speed, while sunburst focuses on high fidelity and fine-grained control.

Common request fields are model, image, mask, prompt, size, n, response_format, and callback_url. For size, use auto or a WIDTHxHEIGHT value. Width and height must be multiples of 16, the long 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. If you use response_format=b64_json, only n=1 is supported.

Handle async jobs and errors cleanly

For long-running work, include a callback target:

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

The asynchronous 200 response is {"task_id":"..."}, and the final result is delivered to the callback. For troubleshooting, check 400 responses for image format, image count, parameter combinations, size format, and mask validity. Check 401 for the API key and Bearer header, 429 for request frequency, and use callbacks if synchronous calls hit 504. Error responses include trace_id; share that ID when reporting issues, not your API key.

Closing pattern

A reliable image editing workflow usually looks like this: host or upload the image, write a preservation-first prompt, add a mask when the edit must stay local, choose a valid canvas size, and log task_id plus trace_id for debugging. That is enough structure to make image editing practical inside product pipelines, internal tools, and creative automation jobs.

Read the full reference in the OpenAI Images Edits API Integration Guide.

Search This Blog

AceDataCloud