A Practical Guide to Editing Images with GPT Image 2 and Masks

A Practical Guide to Editing Images with GPT Image 2 and Masks

When you are building an image workflow, the hard part is rarely “generate a nice picture.” The hard part is changing one specific thing while keeping the rest of the composition stable. The GPT Image 2 / 2.5 image editing API on Ace Data Cloud is useful for that controlled iteration: provide an input image, describe the edit, optionally constrain the editable region with a mask, and receive an edited image URL or base64 result.

What you can do

The API centers on https://api.acedata.cloud/openai/images/edits. The documented workflow supports several practical patterns:

  • Edit an image by passing a public image URL in JSON.
  • Upload a local image with multipart/form-data.
  • Pass multiple reference images through image; JSON accepts one URL or an array of up to 16 URLs, while multipart accepts one or more image file fields.
  • Use a local PNG mask with an Alpha channel to limit the edit to a specific region.
  • Add callback_url for long-running asynchronous jobs.

How it works

An edit request combines an image source, a model, and an instruction. The common fields are model, image, prompt, size, n, response_format, and optionally mask or callback_url. For a simple URL-based edit, send JSON. For local files, use multipart. If you need mask-based local editing, upload the original image and mask in the same multipart request as separate fields: image=@input.png and mask=@mask.png. Do not mix a URL image with a local mask file; pure URL editing requests do not support adding a local mask file.

Start with a URL-based edit

The fastest path is to keep the whole image editable and describe the change precisely. This example asks the model to preserve composition, camera angle, and shadow while changing only color and background.

curl https://api.acedata.cloud/openai/images/edits \
  -H "Authorization: Bearer $ACE_DATA_CLOUD_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, and usage. The edited file URL is returned 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 when your asset is not public

If the image lives on disk, switch to multipart/form-data. This is also the path you need when adding a mask.

curl https://api.acedata.cloud/openai/images/edits \
  -H "Authorization: Bearer $ACE_DATA_CLOUD_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@input.png" \
  -F "prompt=Replace the background with a bright modern studio"

When using multiple references, keep the prompt explicit about the role of each image. The API supports up to 16 reference images, but the instruction still has to say what should change and what should remain fixed.

Use masks for controlled local edits

A mask is the right tool when you want to edit only part of the image. For the official image edit contract, mask must be a PNG with an Alpha channel, must not exceed 4MB, and must have exactly the same dimensions as the first image. Transparent pixels with Alpha value 0 are editable; 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 submit both files together:

curl https://api.acedata.cloud/openai/images/edits \
  -H "Authorization: Bearer $ACE_DATA_CLOUD_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."

The mask constrains the area, but the model may still blend edges naturally. If strict boundaries matter, use clear Alpha edges and repeat in the prompt which content must remain unchanged.

Pick the right model and response shape

The documentation lists 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. Use the base model for the default path, flare when speed is the priority, and sunburst when fidelity and precise control matter.

For size, you can use 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. If size is omitted or set to auto, the model selects the canvas based on the prompt and first reference image.

For production jobs, add a callback_url when you expect longer processing. Asynchronous responses return a task_id, and the final result arrives through the callback.

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

Debugging checklist

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

Error responses include trace_id. Keep that ID for support and never include your API key in reports.

Wrapping up

The practical pattern is simple: start with a URL edit, move to multipart when the asset is local, and add a PNG Alpha mask when you need controlled regional changes. If you are building a design tool, product-image pipeline, or internal creative workflow, that progression keeps the implementation small while giving builders enough control to iterate safely.

Read the full reference in the OpenAI Images Edits API Integration Guide.

Comments

Post a Comment

Popular posts from this blog

Artistic QR Code API Integration Guidance

Image
Artistic QR code is an innovative technological product that combines QR codes with beautiful background images, creating practical and visually appealing works. They not only possess the functionality of traditional QR codes, allowing quick scanning and recognition by smart devices, but also incorporate artistic elements to enhance visual appeal and brand recognition. Some artistic QR codes are even generated by artificial intelligence, fully leveraging modern technology to demonstrate unparalleled innovation and uniqueness. This makes artistic QR codes widely applicable in areas such as brand marketing and advertising. In simple terms, artistic QR codes are the perfect combination of QR code scanning and artistic aesthetics. They not only provide the function of information transmission, but also enhance the user's visual experience, making each scan a delightful artistic enjoyment. Overview of Artworks Let's take a look at a few QR code works: How are they? These are ar...
Read more

How to Configure Claude Code with CC Switch and Ace Data Cloud

Image
If you use Claude Code across a terminal, VS Code, or remote development setup, the awkward part is often not the model itself but the configuration: where should requests go, where should the token live, and how do you switch providers without editing files by hand? This guide walks through a practical setup using CC Switch as the graphical configuration manager and Ace Data Cloud as the Anthropic-compatible base URL. The goal is simple: configure Claude Code once, verify the active endpoint, and keep the setup easy to change later. What you can do With the setup described in the Ace Data Cloud documentation, you can: Manage Claude Code provider configuration through a desktop UI instead of manually editing settings.json . Store an Ace Data Cloud provider with ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN . Switch the active Claude Code provider from CC Switch without rewriting your configuration every time. Use the same provider configuration from the terminal an...
Read more

How to Build a Server-Side Image Editing Workflow with GPT-Image-2

Image
If your product needs image editing, the hard part is rarely the model call itself. The real challenge is building a reliable workflow around user images, reference assets, predictable output sizes, and slow-running jobs without forcing every file through a manual upload step. This guide walks through a practical server-side workflow using the OpenAI Images Edits API on Ace Data Cloud. The focus is gpt-image-2 , because the documented editing flow supports direct image URLs, base64 input, multiple reference images, high-resolution output through size , and asynchronous callbacks. What you can do The edits endpoint is designed for turning one or more input images plus an instruction into a modified output image. In practical terms, you can use it to: Convert an existing infographic or poster into a different visual theme while preserving its layout. Change a product, shelf, room, or object style while keeping the original arrangement stable. Pass image URLs directly f...
Read more