mask_image_url or mask_url? Masked edits on Sume's image APIs

Use mask_image_url on Image 1.0 (POST /v1/image-1.0/generate) and mask_url on POST /v1/images. They do the same job, a masked edit, but the surrounding fields differ: image_urls on one route, input_references on the other.

Both come from Sume's Image 1.0 and Image API docs, read 2026-09-30.

How does Image 1.0 take a mask?

Add mask_image_url alongside image_urls (1 to 10 public HTTPS URLs). Image 1.0 is a compatibility alias for Image Router Auto and is retiring soon; it uses Auto model selection and returns job.model: "sume/auto".

How does POST /v1/images take a mask?

The optional mask_url is documented as a public HTTPS mask URL for ChatGPT Image 2.5 edits, sent with input_references. ChatGPT Image 2.5 takes up to 16 references.

What does an Image 1.0 masked edit look like?

Send the prompt, the source image and the mask URL.

curl -X POST https://api.sume.com/v1/image-1.0/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mask-edit-001" \
  -d '{
    "prompt": "Replace the masked area with a wooden shelf",
    "image_urls": ["https://media.sume.com/artifacts/artf_demo/room.png"],
    "mask_image_url": "https://media.sume.com/artifacts/artf_demo/mask.png"
  }'

Which one should new work use?

Sume's docs point new integrations at POST /v1/images. Use public HTTPS URLs only; localhost, private-network and non-HTTPS URLs are rejected before submission.

How do I check this myself?

Do not mix the field names between routes. Sending mask_url to Image 1.0 or mask_image_url to /v1/images uses a name that route does not document, so stick to the documented name for each route and check the response. The linked docs pages and the catalog endpoint show the current values, and this post reflects them as of 2026-09-30.