Image 1.0
Retiring soon. Image 1.0 is a compatibility alias for Image Router Auto.
For new integrations, use POST /v1/images with model: "sume/auto".
The URLs below keep accepting their legacy request shape, including avatar
references and transparency, but use the same Auto model selection and return
job.model: "sume/auto".
Primary invoke URL:
Model-run alias (same body):
Public model id: sume/image-1.0.
When to use
| Goal | Approach |
|---|---|
| Text → image | prompt only |
| Edit / reference | prompt + image_urls (1–10 public HTTPS URLs) |
| Masked edit | add mask_image_url with image_urls |
Use public HTTPS image URLs only. Localhost, private-network, and non-HTTPS URLs are rejected before submission.
Request fields
| Field | Required | Notes |
|---|---|---|
prompt | Yes | Non-empty string. |
image_urls | No | 1–10 reference/edit image URLs. Prefer over deprecated input_urls. |
mask_image_url | No | Mask image URL for edit flows. |
aspect_ratio | No | Per-model native catalog. 4:5 is Instagram portrait (1080×1350), not 4:3. gpt-image-2 also accepts 5:4 / 9:8 / 4:5. Ignored when image_size is set on custom-pixel models. |
image_size | No | Named presets or { width, height } / WIDTHxHEIGHT on models that accept custom pixels (GPT, Seedream, Flux, Qwen, Recraft). GPT custom: both edges ×16, max edge 3840, aspect ≤3:1, 655,360–8,294,400. On Nano Banana, WxH maps to the native aspect_ratio (1080×1350 → 4:5); exact pixels are a documented post-step via job target_pixels. |
quality | No | low (default), medium, high. Escalate for finals, dense text, or packaging. |
num_images | No | Integer 1–4. Prefer over deprecated n. |
output_format | No | png, jpeg, jpg, webp. Prefer over deprecated format. |
metadata | No | Caller metadata stored on the job; not sent to the provider. |
mode | No | async (default behavior when omitted on most clients), sync, subscribe, webhook. |
webhook_url | No | Public HTTPS callback for terminal delivery when using webhook mode. |
wait_timeout_seconds | No | 0–30. Blocking wait budget for sync / subscribe. |
Deprecated aliases still accepted: input_urls, n, format. Prefer the
non-deprecated names above.
Create an image job
Generate an Image 1.0 job
POST /v1/image-1.0/generate
Required
Reference / edit example:
Reuse the same Idempotency-Key only for the same operation and payload when
retrying after client timeouts. See Jobs and results.
Poll and fetch the result
Submit responses include status_url, result_url, events_url, and optional
cancel_url. Poll until the job is terminal, then fetch the result.
Artifacts
Completed Image 1.0 jobs return Sume-hosted media under result.artifacts[]:
Use the returned Sume media URLs. Raw provider URLs are not part of the public result contract.
Next
- Video 1.0 for motion from prompts or first frames
- Jobs and results for modes, cancellation, and events
- Media inputs for HTTPS URL rules
- Recipes for short copy-paste flows