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

Image editing APIs are most useful when you need to keep an existing visual direction but change one controlled part of the image: a product color, a background, an object inside a mask, or a set of references that should guide the final result.

This guide walks through the GPT Image 2 / 2.5 image editing flow on Ace Data Cloud from a builder's point of view: what the endpoint accepts, when to use URL editing versus multipart uploads, and how to avoid the common mistakes that make image edits unpredictable.

What you can do

The image editing endpoint is POST https://api.acedata.cloud/openai/images/edits. It accepts an editing prompt, one or more input images, and a model such as gpt-image-2, gpt-image-2.5-flare, or gpt-image-2.5-sunburst. The same model family also has :official variants, and gpt-image-2 also supports :reverse.

In practical terms, you can:

Edit from a hosted image URL using a JSON request.
Upload local images with multipart/form-data.
Provide up to 16 reference images through repeated multipart image fields or a JSON array of URLs.
Use a PNG mask with :official models to limit which area should be editable.
Choose size, n, response_format, and optionally callback_url for longer-running jobs.

How it works

There are two main request shapes. If your input image is already hosted, send JSON with model, image, prompt, and optional fields such as size. If your local files are on disk, use multipart/form-data and upload each file with image=@input.png.

The response for a synchronous request includes created and data, where data[0].url is the edited image URL. A successful JSON response may also include success, task_id, trace_id, model, and usage. For long-running work, add callback_url; the asynchronous 200 response is {"task_id":"..."}, and the final result is sent to your callback after completion.

Start with URL-based editing

URL editing is the simplest path when the input asset already lives somewhere reachable by the API. The important habit is to write the prompt like an edit instruction, not a generic image generation prompt. Tell the model what must remain unchanged and what should change.

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

That example shows the pattern: use image for the input, describe preservation constraints in the prompt, and set size when you need a predictable canvas.

Upload local files when the image is not public

When your image is on disk, switch to multipart. This is also the path 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 multipart requests. In JSON requests, image can be a single URL or an array of URLs, with up to 16 references supported by the GPT Image series.

Use masks for local, controlled edits

For localized editing with :official models, add a mask file in the same multipart request. 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 area that may be edited; non-transparent pixels mark areas that should be preserved.

from PIL import Image, ImageDraw

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

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 mix a URL original image with a local mask file. When using mask, upload the original image and mask separately in the same multipart request.

Choose parameters deliberately

The common fields are straightforward: model selects the image editing model; image supplies the input image or references; mask is optional and only works as a multipart file upload; prompt contains the edit instruction; size may be auto or a valid WIDTHxHEIGHT; n supports 1–10, though only 1 is supported when response_format=b64_json; response_format can be url or b64_json; and callback_url enables asynchronous callbacks.

For explicit sizes, 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 omit size or use auto, the model chooses the canvas based on the prompt and first reference image.

Troubleshooting checklist

400: check image format and count, parameter combinations, and size format. With mask, verify the PNG Alpha channel, 4MB limit, and matching dimensions.
401: check the API key and Authorization: Bearer header.
429: reduce request frequency.
504: switch to asynchronous callbacks.

Error responses include trace_id. Keep that ID when reporting an issue, but never share your API key.

Where to go next

For a first implementation, start with a single URL edit, then move to multipart only when you need private local files, multiple references, or a mask. The endpoint is flexible, but most good results come from precise preservation instructions and a small number of well-chosen parameters. You can read the full field reference in the OpenAI Images Edits API Integration Guide.

Search This Blog

AceDataCloud