A Practical Guide to Image Editing with GPT Image 2

When you need to change one part of an image without rebuilding the whole composition, a text-to-image endpoint is often the wrong tool. An image editing API is more useful because it starts from a reference image, accepts an instruction, and returns a modified result that can preserve layout, lighting, and subject identity.

This guide walks through the GPT Image 2 / 2.5 image editing workflow exposed through Ace Data Cloud. The goal is practical: send an existing image URL or local file, describe the edit, optionally constrain the editable region with a mask, and handle results safely in production.

What you can do

The editing endpoint is https://api.acedata.cloud/openai/images/edits. It accepts a source image plus an editing prompt and returns an edited image URL or base64 payload depending on response_format.

• Edit from a remote image URL with a JSON request.
• Upload one or more local images with multipart/form-data.
• Use up to 16 reference images for GPT Image series edits.
• Use a PNG mask with Alpha transparency when you need local edits.
• Choose models such as gpt-image-2, gpt-image-2.5-flare, or gpt-image-2.5-sunburst, including documented :official variants.

How it works

At the simplest level, you send four things: an authorization header, a model, an image, and a prompt. For URL-based editing, image can be a single URL or an array of URLs. For local files, use repeated image form fields.

The prompt should describe both the change and what must remain unchanged. For example, instead of saying “make it orange,” a better instruction is: keep the camera angle, subject, tabletop, and shadow unchanged; change only the mug color and background. This is the difference between an edit request and a new generation request.

Edit an image from a URL

URL editing is the cleanest starting point for server-side apps because you do not need to stream binary files from your backend. The documented JSON request uses model, image, prompt, and optionally size.

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 fields such as success, task_id, trace_id, created, model, data, and usage. The edited image URL is available at data[0].url.

{
  "success": true,
  "task_id": "49848451-c624-4df9-9dc2-494018daaf4c",
  "trace_id": "5ac021c2-2891-4eed-bfcf-4c6668ac1be1",
  "created": 1788831893,
  "model": "gpt-image-2",
  "data": [
    {
      "url": "https://cdn.acedata.cloud/assets/examples/gpt-image/49848451-c624-4df9-9dc2-494018daaf4c_0-b6d780a732ca.png"
    }
  ],
  "usage": {
    "input_tokens": 775,
    "output_tokens": 1372,
    "total_tokens": 2147
  }
}

Upload local images

If your source image is not already hosted, use multipart/form-data. This is also the required path when you want to use a local mask file.

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"

For multi-reference workflows, pass image repeatedly in multipart requests, or pass an array of image URLs in JSON. Keep the order intentional: the first image is usually the base image, and later images act as references.

Constrain edits with a mask

When using :official models, the documented multipart contract supports mask. The mask must be a PNG with an Alpha channel, must match the dimensions of the first image, and must not exceed 4MB. Transparent pixels with Alpha value 0 mark the area that can be edited; 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 send the original image and mask together:

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. The original image and the mask need to be uploaded separately in the same multipart request.

Parameters and production checks

Common fields include model, image, mask, prompt, size, n, response_format, and callback_url. size 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.

For long-running jobs, add a callback_url. The asynchronous response returns a task_id, and the final result is delivered through the callback. For troubleshooting, check parameter combinations and image constraints on 400, the Bearer header on 401, request frequency on 429, and consider callbacks when a request reaches 504. Error responses include trace_id; share that ID when reporting an issue, not your API key.

Used carefully, image editing becomes a reliable building block: product mockups, localized creatives, controlled background replacement, and workflow automation all start with the same discipline—preserve what matters, describe the edit precisely, and validate the returned image URL. For the complete field list and examples, read the OpenAI Images Edits API Integration Guide.