How to Build a Reliable Image Editing Workflow with GPT Image 2
Image editing APIs are most useful when they behave like a predictable production tool: you provide a source image, describe a constrained change, and get an edited result without rebuilding your whole creative pipeline.
What you can do
The Ace Data Cloud OpenAI Images Edits API lets you edit existing images through https://api.acedata.cloud/openai/images/edits. The same endpoint supports URL-based editing for hosted images and multipart/form-data uploads for local files.
From the documentation, the core fields are straightforward:
model: for examplegpt-image-2,gpt-image-2.5-flare,gpt-image-2.5-sunburst, and their supported variants.image: a single URL, an array of URLs, or one or more multipart file fields.prompt: the editing instruction.mask: an optional PNG mask for local editing with the official multipart contract.size:autoor a compliantWIDTHxHEIGHT.n,response_format, andcallback_urlfor output count, URL/base64 response style, and asynchronous callbacks.
How it works
There are two practical modes. If your image is already online, send JSON with an image URL and a specific prompt. This is ideal for automated catalog edits, blog assets, thumbnails, and design variations where the source image is stored in a CDN or object bucket.
If the image is local, use multipart/form-data and upload it with image=@input.png. For localized changes, upload a separate mask=@mask.png in the same multipart request. The mask workflow is important when you need to preserve most of the image and only change a bounded region.
Start with a URL-based edit
A URL request is the fastest way to test the API because it avoids local file handling. The following example keeps the documented request shape: Bearer authentication, JSON content, model, image, prompt, and 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 success, task_id, trace_id, created, model, data with an output url, and usage. In a production app, I would store both task_id and trace_id. The output URL is what your product uses, while the trace ID is useful when diagnosing errors.
Use multipart upload for local files
When the source image is not hosted, switch to multipart. The shape is simpler than many image pipelines because you do not need to pre-upload the file somewhere else.
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"The API can receive multiple references: in JSON, image can be an array of URLs; in multipart, pass the image field more than once. The GPT Image series supports up to 16 reference images, which is useful for style references, brand assets, or before/after workflows.
Constrain edits with a mask
For local editing, mask gives you more control. The documented requirements are strict and worth validating before calling the API: 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 0 mark areas that may be edited; non-transparent pixels indicate areas that should be retained.
Here is the documented pattern for creating a central transparent 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 send the original image and mask together. The documented mask example uses an official model variant:
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."Call it from Python
If your stack already uses the OpenAI Python SDK, the API can be called by pointing base_url to Ace Data Cloud and using client.images.edit.
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.acedata.cloud/openai",
)
with open("input.png", "rb") as image, open("mask.png", "rb") as mask:
result = client.images.edit(
model="gpt-image-2:official",
image=image,
mask=mask,
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."
),
)
print(result.data[0].url)Production notes
sizecan beautoor a compliantWIDTHxHEIGHT. Width and height must be multiples of 16, the longer side must not exceed 3840, total pixels must be 655,360–8,294,400, and the aspect ratio must not exceed 3:1.- When
response_formatisb64_json, onlyn=1is supported. - For long-running jobs, pass
callback_url. The asynchronous 200 response is{"task_id":"..."}, and the final result is sent through the callback. - For troubleshooting:
400usually means image, mask, quantity, parameter, or size issues;401means API key or Bearer header;429means request frequency;504suggests switching to asynchronous callbacks.
The main builder lesson is simple: use JSON URL edits for fast hosted-image workflows, multipart uploads for local files, and masks when you need reliable local control. Read the full field reference in the OpenAI Images Edits API guide.
Comments
Post a Comment