A Practical Guide to Image Editing with GPT Image 2

When you need to modify an existing image without rebuilding the whole asset from scratch, the hard part is usually control: keeping the composition stable while changing only the parts you asked for.

This guide walks through the GPT Image 2 / 2.5 image editing API on Ace Data Cloud. The goal is not to cover every possible creative use case, but to show the practical request shapes you will actually use as a builder: URL-based editing, local image upload, mask-constrained edits, and async callbacks for slower jobs.

What you can do

The image edits endpoint lets you send an existing image plus an editing instruction, then receive an edited image URL or base64 result depending on response_format. The documented endpoint is:

POST https://api.acedata.cloud/openai/images/edits

Common use cases include:

Changing a product color while preserving the camera angle, lighting, and layout.
Replacing a background for a product or profile image.
Using up to 16 reference images when your edit needs more context.
Using a PNG mask to constrain where the model is allowed to modify the image.
Sending a callback_url for longer-running image tasks.

The core fields you will see most often are model, image, prompt, size, n, response_format, mask, and callback_url.

How it works

At a high level, the request contains three things: the model, one or more input images, and a plain-language editing instruction. Ace Data Cloud exposes this through the OpenAI-compatible image editing route at https://api.acedata.cloud/openai/images/edits.

For simple URL edits, send JSON with an image URL. For local files, use multipart/form-data. If you need a mask, the original image and mask must be uploaded as separate multipart file fields: image=@input.png and mask=@mask.png. Do not combine a remote image URL with a local mask file.

The model options documented for this workflow 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, pick the model based on whether you want the default path, an official API channel, a speed-focused variant, or a higher-fidelity control variant.

Edit an image from a URL

The fastest path is a JSON request with an image URL. This is useful when your source asset is already hosted on a CDN or object store.

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"
  }'

Notice how specific the prompt is. It says what to change, but it also names what must remain unchanged: the mug, tabletop, camera angle, portrait layout, and soft shadow. That kind of negative control is often the difference between a useful edit and an image that looks like a new generation.

A successful synchronous response includes fields such as success, task_id, trace_id, created, model, data, and usage. The edited image URL is returned under data[0].url.

Upload local files with multipart

When the source image is local, use multipart/form-data instead of JSON. This is also the request format you need when working with masks.

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"

You can pass image repeatedly. In JSON requests, image can be a single URL or an array of URLs. The GPT Image series supports up to 16 reference images.

Use a mask for controlled local edits

For localized editing, the mask field defines where changes are allowed. The mask must be a PNG with an Alpha channel, must not exceed 4MB, and must exactly match the dimensions of the first image. Transparent pixels with Alpha value 0 mark areas that can be edited; non-transparent pixels mark areas to retain.

Here is a small Python snippet that creates a mask with a transparent central rectangle:

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 both files in the same 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."

The mask constrains the editing area, but the model may still blend edges naturally. When you need a stricter boundary, use clear Alpha edges and repeat in the prompt which content must remain unchanged.

Choose sizes, output formats, and async behavior

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. If you omit size or use auto, the model selects the canvas based on the prompt and the first reference image.

The n field supports values from 1 to 10, but only 1 is supported when response_format is b64_json. For normal web workflows, response_format=url is usually easier because you can store and render the returned asset directly.

For long-running edits, 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 processing completes. If you receive a 504, the documented troubleshooting path is to switch to asynchronous callbacks.

Practical debugging checklist

400: check image format, image quantity, parameter combinations, and size format. For masks, check the PNG Alpha channel, 4MB limit, and dimension match.
401: check the API key and Bearer header.
429: reduce request frequency.
504: use asynchronous callbacks.

Error responses include a trace_id. Keep that value for support or internal debugging, but never share your API key.

Where to go next

If you are building product-image tooling, internal creative review flows, or a small asset automation pipeline, start with URL editing first. Once you trust the prompt pattern, add multipart uploads. Use masks only when you truly need localized control.

For the full reference fields and examples, read the OpenAI Images Edits API Integration Guide.

Search This Blog

AceDataCloud