2026-10-07

Image 1.0 to POST /v1/images: image_urls, num_images, mask mapped

Moving from /v1/image-1.0/generate to /v1/images on Sume: image_urls becomes input_references, num_images becomes n, and the default mode becomes sync.

5 min readSume

All posts

Sume says Image 1.0 is retiring soon, and that new integrations should call POST /v1/images, with model: "sume/auto" if you want Sume to choose. The legacy URL keeps working as a compatibility alias, but the request fields have different names and the default wait is different. This is the field map.

Field map

Image 1.0 request fields and their Images API form (read 2026-10-07)
Image 1.0 (/v1/image-1.0/generate)	Images API (/v1/images)	Notes
prompt	prompt	Same
image_urls (1 to 10 URLs)	input_references: [{type: "image_url", image_url: {url}}]	Up to 10, or 16 on ChatGPT Image 2.5; public HTTPS only
mask_image_url	mask_url	Only ChatGPT Image 2.5 accepts it
num_images (1 to 4)	n	Request cap 10, per-model cap from the catalog
quality: low (default), medium, high	quality: auto, low, medium, high; xhigh and max on 2.5	Default differs by model: high on ChatGPT Image 2.5, medium on Ideogram 4.5
format / output_format	output_format	png, jpeg or webp, if the row lists it
transparency	background: transparent	ChatGPT Image 2.5 only

Response differences

Image 1.0 jobs return result.artifacts[] once you read the job result. The Images API answers a sync request with 200 and data[].url plus usage.cost, or 202 with the standard job envelope when the 30-second wait runs out. Branch on the status code.

job.model stays sume/auto on the legacy route. On the new route, model echoes what you sent.

Default mode flips

Image 1.0 behaves like the other generate routes: async unless you say otherwise. POST /v1/images defaults to mode: "sync" with wait_timeout_seconds: 30. If your worker used to expect a 202 and poll, either send mode: "async" on the new route or handle both codes. Resubmitting after a timeout is not needed: poll the job, or reuse the same Idempotency-Key for the same payload.

A converted request

The old call below becomes the new one by renaming three fields:

# before: POST /v1/image-1.0/generate
{"prompt": "swap the background to soft daylight",
 "image_urls": ["https://example.com/product.png"],
 "num_images": 2, "quality": "medium"}

# after: 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"}}],
 "n": 2, "quality": "medium", "mode": "async"}

Move over in steps

List the fields your code sends today and map each to the table above before changing any call.
Check the target model with GET /v1/images/models first; a field the row does not list returns 400 unsupported_parameter.
sume/auto is the Sume-only id and is not a catalog row, so pin a listed id when you need to know which model ran.
Run the same prompt through both routes during the move and compare status codes and response shape.
Log usage.cost on the new route; cost is cost_usd times n.

Check before you cut over

If you need a model-specific parameter such as mask_url, pin a model that lists it instead of sume/auto.
Read the Image 1.0 page and the Image API page side by side during the move.
Keep your poll fallback: Jobs and results says not to resubmit a paid job for the same intent.