GPT Image mask edit API: how to use mask_url on GPT Image 2.5

To edit part of an image with GPT Image 2.5 on Sume, send the source picture in input_references, a public HTTPS mask image in mask_url, and a prompt that says what should change in the masked area. mask_url is listed only on the two 2.5 ids, openai/gpt-image-2.5 and openai/gpt-image-2.5-sunburst.

OpenAI's image generation guide adds two rules for masks: the mask must have an alpha channel, and white areas mark the regions to edit. It also says masking with GPT Image is prompt-based, so the model uses the mask as guidance and may not follow its exact shape. Sume's Image API docs describe mask_url only as an optional public HTTPS mask for 2.5 edits. All read 2026-09-29.

What does a masked edit request look like?

Keep the prompt about the change, not the whole scene, and set aspect_ratio to auto so the output keeps the source's shape. Both the picture and the mask must be reachable at public HTTPS URLs; localhost and private-network URLs are rejected before submission.

curl -X POST "https://api.sume.com/v1/images" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2.5-sunburst",
    "prompt": "Replace the masked wall with exposed red brick. Leave everything else unchanged.",
    "input_references": [
      { "type": "image_url", "image_url": { "url": "https://example.com/room.png" } }
    ],
    "mask_url": "https://example.com/room-mask.png",
    "aspect_ratio": "auto"
  }'

Will the edit stay inside the mask?

Do not count on pixel-exact edges. OpenAI describes the mask as guidance, so an edit can bleed past the boundary. Check the result against your source, and if a strict boundary matters, composite the edited region back onto the original in your own code.

What are the mask requirements?

What if I send mask_url to another model?

It is rejected. A parameter a model does not list returns 400 unsupported_parameter instead of being dropped, so a mask never silently does nothing. ChatGPT Image 2 (openai/gpt-image-2) does not list mask_url; the catalog at GET /v1/images/models shows what each model accepts. If you cannot use a mask, describe the region in words and use reference-based editing.