Image 1.0 to POST /v1/images: image_urls becomes input_references

To move a Sume Image 1.0 request to POST /v1/images, change four things: add a model (sume/auto keeps Auto routing), turn image_urls into input_references objects, rename mask_image_url to mask_url, and rename num_images to n. Also set quality yourself, because the defaults differ, and note that /v1/images waits up to 30 seconds by default where Image 1.0 is async. Sume says it will retire Image 1.0 soon.

Field by field

Both routes are documented on Sume's docs pages for Image 1.0 and the Image API. Image 1.0 accepts 1 to 10 image URLs in image_urls and still accepts the deprecated aliases input_urls, n and format. The Image API takes references as objects of type image_url.

Before and after

The first body is an Image 1.0 edit. The second is the same intent on /v1/images.

// Image 1.0
{"prompt": "Swap the background to soft daylight",
 "image_urls": ["https://example.com/product.png"],
 "quality": "medium", "num_images": 2}

// POST /v1/images
{"model": "sume/auto", "prompt": "Swap the background to soft daylight",
 "input_references": [{"type": "image_url",
   "image_url": {"url": "https://example.com/product.png"}}],
 "quality": "medium", "n": 2, "mode": "async"}

Behavior that changes

Result shape differs. Image 1.0 returns a job with result.artifacts[]. POST /v1/images returns data[].url when it finishes inside the wait budget, and the job envelope with 202 when it does not. The job model stays sume/auto in both cases when you use Auto.

Rejections also differ in spirit. On /v1/images, a field the selected model does not list returns 400 unsupported_parameter instead of being dropped. Seed, output_compression and streaming are in the schema but not served in v1, so do not carry them over.

If you want a fixed model rather than Auto, pick the catalog row from GET /v1/images/models, read its supported_parameters, and send only those fields.

Checklist

Work through these in order when you port a caller.

• Add model, and keep sume/auto if you want Auto routing.
• Rename image_urls to input_references and wrap each URL in an image_url object.
• Rename mask_image_url to mask_url and use a GPT Image 2.5 row.
• Rename num_images to n and keep it inside the row's ceiling from the catalog.
• Write quality explicitly, since the defaults differ.
• Decide on mode and handle a 202 envelope.
• Remove deprecated aliases input_urls, n (as an Image 1.0 alias) and format.
• Re-run one request and compare data[].url with the old result.artifacts[].url.