Edit part of a product ad image with a mask: ChatGPT Image 2.5

To edit one part of a product ad image, send the photo in input_references and a public HTTPS mask_url to ChatGPT Image 2.5 on Sume's POST /v1/images, and describe the change in the prompt. Sume's docs list openai/gpt-image-2.5 and openai/gpt-image-2.5-sunburst with up to 16 image references and an optional mask. A batch tool such as Higgsfield Ads Studio, per its 2026-09-30 changelog entry, works from a website link; a mask edit is the other direction, fixing one ad you already like.

Facts come from Sume's Image API docs, read 2026-10-02.

What does the request look like?

The body below uses quality: high, which is also the default when quality is omitted. Mode async returns a job you poll, because high quality is one of the settings the docs say can run past the 30-second blocking wait.

{
  "model": "openai/gpt-image-2.5",
  "prompt": "Replace the background with a warm kitchen counter. Keep the product unchanged.",
  "input_references": [
    {"type": "image_url",
     "image_url": {"url": "https://example.com/product.jpg"}}
  ],
  "mask_url": "https://example.com/background-mask.png",
  "quality": "high",
  "mode": "async"
}

What limits apply?

The docs give image_size rules for custom pixels: both edges multiples of 16, a maximum edge of 3840, aspect ratio at most 3:1, and 655,360 to 8,294,400 total pixels. Reference and mask URLs must be public HTTPS; localhost and private-network URLs are rejected before submission.

How is it billed?

The docs give Fal token rates for this model family and say the estimate depends on quality and size, with auto quality reserving max. Set quality explicitly to keep the reservation predictable, and read the cost on the job result.

What can go wrong?

A mask that does not line up with the photo changes the wrong region. Check the first result before running a batch. Ad variations from one image covers the batch step.

Make the mask in an image editor, white where the model may change and black where it must not, and save it at the same pixel size as the photo. Test the mask against the photo before sending, and check the edge of the product in the result. Reuse the same mask for every variation of that photo.