Image 1.0
Use Image 1.0 when you need still images from a text prompt, optional reference images, or a mask-guided edit. Sume picks the provider model; callers never send provider model ids.
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 | 1:1, 9:16, 16:9, 4:3, 3:4, plus gpt-image-2 5:4 / 9:8. Ignored when image_size is set. |
image_size | No | Named presets (square, square_hd, portrait_16_9, landscape_16_9, landscape_4_3, portrait_4_3) or { width, height } / WIDTHxHEIGHT for gpt-image-2. Custom pixels: both edges ×16, max edge 3840, aspect ≤3:1, 655,360–8,294,400. Wins over aspect_ratio. |
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