A Practical Guide to GPT Image 2 Image Editing with URL References and Masks

A Practical Guide to GPT Image 2 Image Editing with URL References and Masks

When an image-editing workflow needs to preserve composition while changing only specific visual details, a plain text-to-image prompt is usually too loose; you need a repeatable edit endpoint that accepts reference images, explicit instructions, and, when necessary, a mask.

What you can do

The Ace Data Cloud OpenAI Images Edits API exposes POST https://api.acedata.cloud/openai/images/edits for editing existing images with GPT Image 2 and GPT Image 2.5 model variants. In practical terms, you can:

  • Send a public image URL and describe what should change.
  • Upload a local image with multipart/form-data.
  • Provide multiple reference images through the image field, up to 16 references for the GPT Image series.
  • Use a PNG mask with an Alpha channel when you need to constrain the editable region.
  • Choose URL output with response_format=url or base64 output with response_format=b64_json.
  • Use callback_url for longer-running jobs where a synchronous request may not be ideal.

How it works

The editing contract is simple: authenticate with a Bearer API key, send an image reference or file upload, choose a supported model, and pass a prompt that explains the final image you want. The core fields are model, image, prompt, size, n, response_format, mask, and callback_url.

For URL-based editing, image can be a single URL or an array of URLs. For local files, use multipart fields such as image=@input.png. If you use a mask, both the original image and the mask must be uploaded as multipart files in the same request; do not combine a URL source image with a local mask file.

Model choices documented for this endpoint include 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. The names are worth keeping explicit in your code because they express different routing and quality/speed preferences.

Edit from an image URL

The fastest path is to start with an image URL. This is useful for build scripts, content tools, CMS integrations, and design-review bots where the source asset already lives on a CDN.

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, and usage. The edited image URL appears at data[0].url. Keep the trace_id around for troubleshooting, especially if a user reports a bad edit or an API error.

Upload local files when the image is not public

If your source asset is local, private, or generated earlier in the same pipeline, use multipart/form-data. The field names remain straightforward:

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 for multi-reference edits. In JSON requests, the same concept is represented as an array of image URLs. This is useful when one image supplies the subject, another supplies styling, and a third provides layout or material reference.

Use masks for controlled local edits

Masks are the practical difference between “make this image better” and “change only this area.” The documented mask rules are strict and worth validating before you call the API:

  • mask must be a PNG with an Alpha channel.
  • The mask must not exceed 4MB.
  • The mask dimensions must exactly match the first image.
  • Transparent pixels with Alpha value 0 are editable; non-transparent pixels are retained.
  • Black-and-white RGB images without transparency are not valid masks.

Here is a small Python snippet that creates a transparent central rectangle in a mask:

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

Canvas size, callbacks, and troubleshooting

The size field 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. If size is omitted or set to auto, the model chooses a canvas based on the prompt and the first reference image.

For longer jobs, include a callback target:

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

The documented asynchronous response is {"task_id":"..."}, and the final result is delivered through the callback. For common failures, check request shape first: 400 usually points to image format, image quantity, parameter combinations, size format, or mask validity; 401 means the API key or Bearer header needs attention; 429 indicates request frequency; and 504 is a sign to switch to asynchronous callbacks.

If you are building a content tool, a CMS assistant, or an internal asset pipeline, start with URL editing, add multipart uploads when files are private, and only introduce masks where deterministic local control is worth the extra validation. The full reference is available 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