How to Edit Images with GPT Image 2 Using a URL, a Mask, or Python

Image editing becomes awkward when a workflow has to preserve composition, accept references from different sources, and still expose a predictable API contract. This guide shows how to use the GPT Image editing endpoint through Ace Data Cloud for URL-based edits, local multipart uploads, and masked changes that keep selected regions intact.

What you can do

The Images Edits API accepts an original image plus an editing instruction and returns either a URL or base64 output. The JSON form is useful when the source image is already hosted. The multipart form is the route to use for local files and masks.

• Send one image URL or an array of up to 16 image URLs in a JSON request.
• Upload one or more local image files with multipart/form-data.
• Use a PNG mask to identify an editable area for local editing.
• Choose synchronous output or provide callback_url for a long-running asynchronous request.

How the request works

The endpoint is https://api.acedata.cloud/openai/images/edits. Authenticate with an API key in the Bearer header and send JSON or multipart form data. The central fields are model, image, and prompt. For a straightforward URL edit, gpt-image-2 is a practical starting point.

Edit a hosted image with curl

When the input is publicly reachable, keep the request small and explicit. The prompt should say what must remain unchanged as well as what should change. That makes the edit easier to reason about in an automated pipeline.

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://example.com/input.png",
    "prompt": "Keep the camera angle, composition, lighting, and objects unchanged. Replace the background with a clean dark navy studio background.",
    "size": "1024x1024",
    "response_format": "url"
  }'

A synchronous response includes created and data. The generated image URL is in data[0].url when the request succeeds. The size field can be auto or a custom WIDTHxHEIGHT that satisfies the documented dimensions and aspect-ratio constraints.

Use local files and a mask

For a file on disk, switch to multipart form data. A mask is optional, but it is valuable when the goal is a local replacement rather than a full-scene reinterpretation.

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 everything outside the transparent mask unchanged. Inside the masked area, replace the empty tabletop with a small blue ceramic vase."

The mask must be a PNG with an Alpha channel, no larger than 4MB, and exactly the same dimensions as the first image. Transparent pixels with Alpha 0 mark areas that may be edited; non-transparent pixels are preserved. A black-and-white RGB image without transparency is not a valid mask.

One important implementation detail: do not combine a URL-based original image with a local mask file. Masked editing requires the original image and mask to be uploaded separately in the same multipart request.

Create a mask in Python

A mask can be generated from the source image with Pillow. This example preserves the entire image except for a transparent rectangle in the center.

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")

The same contract can be used through the OpenAI Python SDK by setting base_url to https://api.acedata.cloud/openai and calling client.images.edit. Pass the opened image and mask files separately, select gpt-image-2:official, and print result.data[0].url.

Choose output and handle failures

The API supports response_format values of url and b64_json; only one image is supported when using b64_json. The n field accepts 1–10, while callback_url can be supplied when a long-running request should complete through a webhook. An asynchronous 200 response contains a task_id, and the completed result is sent to the callback.

• 400: check image count, format, parameter combinations, size, and mask Alpha/dimensions.
• 401: check the API key and Bearer header.
• 429: reduce request frequency.
• 504: use asynchronous callbacks.

Error responses include a trace_id. Keep that identifier when debugging, but never include the API key in a support report.

Put it into a builder workflow

For a content pipeline, start with URL edits when assets already live in object storage. Use multipart uploads when your worker owns the source file, and introduce masks when only a bounded region should change. Keep the preservation instructions in the prompt, validate the output URL or callback payload, and log the trace_id rather than secrets. That gives a small, composable image-editing step that can sit inside a CLI tool, a web worker, or an IDE automation without hiding the underlying request.

For the complete field list and current enumerations, see the OpenAI Images Edits API integration guide.