120 masked banner edits on GPT Image 2.5: $2.97, $6.68 or $26.70

Editing 120 banners through mask_url on GPT Image 2.5 costs $2.97 at low quality, $6.675 at medium and $26.70 at high, using the per-image catalog rows. The trap is the default: the Image API says that if you omit quality, it is high. A batch you forgot to tag costs nine times the low price.

Which models take a mask

Sume lists mask_url for the two ChatGPT Image 2.5 rows, openai/gpt-image-2.5 and openai/gpt-image-2.5-sunburst. They accept up to 16 reference images, an optional mask_url, and background: auto|transparent|opaque. Other image rows reject mask_url with 400 unsupported_parameter, so a loop over a mixed model list fails on the first non-GPT row.

The mask must be a public HTTPS URL, like every reference. Edit calls with input_references should also send aspect_ratio: "auto" to match the reference, because omitting the field is not the same as auto.

Read the bill from the response

The three prices are catalog tiers. An edit that carries reference images also carries input tokens, and the Image API notes that input token counts are estimates. The response usage.cost field is the amount Sume billed, so log it for the first 5 edits and compare it with the table before you launch the other 115.

For banners the usual aim is to change a price tag or swap a badge, which needs only a small masked region. Try low first. If the edge of the masked area looks soft on three samples, move to medium rather than to high.

Request shape

A masked edit is an ordinary POST /v1/images call with the source image in input_references, the mask in mask_url, and an explicit quality. Use mode: "async" for a batch of 120, since slow configurations can return a 202 job envelope instead of the images.

OpenAI's mask rules apply to the file you send, so check size and alpha before a big run. The post on mask rules and alpha walks through the checks that prevent a silent no-op.

{
  "model": "openai/gpt-image-2.5",
  "prompt": "Replace the price tag with 'SALE 30% OFF', keep everything else",
  "input_references": [{"type": "image_url", "image_url": {"url": "https://example.com/banner-017.png"}}],
  "mask_url": "https://example.com/mask-017.png",
  "aspect_ratio": "auto",
  "quality": "low",
  "mode": "async"
}

Plan the quality ladder

A cheap way to run 120 edits is a ladder. Send all 120 at low ($2.97). Review. Re-send the failures at medium. Re-send what is still wrong at high. If 15 fail at low and 4 fail at medium, the total is $2.97 + 15 x $0.055625 + 4 x $0.2225 = $4.694375, against $26.70 for running everything at high.

The ladder works because a failed edit is visible. A wrong price tag or a smeared logo is easy to spot on review.

What to put in the mask

Keep the masked region as small as the change needs. A price badge covers a few percent of the frame, and the rest of the banner should come back unchanged. If the model changes pixels outside the mask, treat that batch as failed and tighten the mask before you re-run.

Store the mask beside the banner under the same ID, so that a batch of 120 is 120 source files, 120 masks and 120 outputs that you can pair by name.