A Practical Guide to Editing Images with GPT Image 2 on Ace Data Cloud

Image editing APIs are most useful when they let you keep the parts of an image that already work, change only what needs to change, and fit naturally into an existing build pipeline.

What you can do

The GPT Image 2 / 2.5 image editing API on Ace Data Cloud gives builders a direct endpoint for transforming an existing image with a text instruction. The core endpoint is https://api.acedata.cloud/openai/images/edits. You can call it with a JSON body when your source image is already hosted at a URL, or with multipart/form-data when you need to upload local files.

At a practical level, this covers workflows such as:

Changing a product color while preserving composition, camera angle, and shadows.
Replacing a background without rebuilding the subject from scratch.
Editing a constrained region with a PNG alpha mask.
Sending asynchronous jobs to a callback_url when the request may take longer.

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 non-official variants are billed by successfully generated image, while the :official variants are billed from actual token usage in the response and usage records.

How it works

The simplest request has four moving parts: model, image, prompt, and optionally size. In JSON mode, image can be a single URL or an array of up to 16 URLs. In multipart mode, you upload one or more image file fields. If you use mask, you must use local file uploads because the original image and the mask are uploaded together as separate multipart fields.

The prompt should be explicit about both the desired edit and the parts that must remain unchanged. For example, the source documentation shows an instruction that keeps the mug, tabletop, camera angle, portrait layout, and soft shadow unchanged, while changing only the mug color and background. That style of prompt is worth copying: it reduces ambiguity and helps the model understand the edit boundary.

Edit from an image URL

If your input image is already on a CDN or object store, use a JSON request. This is a good fit for web apps where users upload assets first and your backend stores the URL before calling the editing API.

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://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 synchronous success response includes success, task_id, trace_id, created, model, data, and usage. The edited image URL is returned inside data[0].url. Keep the trace_id around for debugging; the docs note that error responses include it and that you should provide the trace ID, not the API key, when reporting issues.

Upload local images

For local files, use multipart/form-data. This is also the path you need when the edit uses a mask.

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. The GPT Image series supports up to 16 reference images, which is useful when the first image is the base canvas and later images provide style, product, or identity references.

Constrain edits with a mask

Use mask when you want local editing rather than a whole-image reinterpretation. 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 the editable area; non-transparent pixels mark the preserved area.

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

One important implementation detail: do not combine a URL original image with a local mask file. For masked editing, upload the original image and mask separately through image=@input.png and mask=@mask.png.

Parameters and production checks

The common fields are model, image, mask, prompt, size, n, response_format, and callback_url. response_format can be url or b64_json; when response_format=b64_json, only n=1 is supported.

For size, use auto or a WIDTHxHEIGHT value that follows the documented constraints: 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 aspect ratio must not exceed 3:1.

For long-running work, include a callback:

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

The async 200 response is {"task_id":"..."}, and the final result is returned to the callback after completion. For troubleshooting, check image format, image count, parameter combinations, and size format on 400; API key and Bearer header on 401; request frequency on 429; and consider switching to asynchronous callbacks on 504.

If you are building an editor, a product-image pipeline, or a content automation tool, the clean mental model is simple: store your base image, describe the edit precisely, use masks only when the boundary matters, and keep trace_id in logs. For the complete field reference, see the OpenAI Images Edits API documentation.

Search This Blog

AceDataCloud