---
title: Image 1.0
description: Generate and edit images with Sume Image 1.0 using prompt, reference, and mask inputs.
---

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:

```text
POST /v1/image-1.0/generate
```

Model-run alias (same body):

```text
POST /v1/models/sume/image-1.0/runs
```

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

<!-- api-call-example:image-generate -->

Reference / edit example:

```bash
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: image-edit-001" \
  -d '{
    "prompt": "Keep the product identical; swap the background to a soft daylight studio",
    "image_urls": ["https://example.com/product.png"],
    "quality": "medium",
    "aspect_ratio": "4:3"
  }'
```

Reuse the same `Idempotency-Key` only for the same operation and payload when
retrying after client timeouts. See [Jobs and results](/workflows/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.

```bash
curl https://api.sume.com/v1/jobs/job_123/status \
  -H "Authorization: Bearer $SUME_API_KEY"

curl https://api.sume.com/v1/jobs/job_123/result \
  -H "Authorization: Bearer $SUME_API_KEY"
```

## Artifacts

Completed Image 1.0 jobs return Sume-hosted media under `result.artifacts[]`:

```json
{
  "id": "job_...",
  "status": "completed",
  "result": {
    "artifacts": [
      {
        "id": "artifact_...",
        "type": "image",
        "url": "https://media.sume.com/artifacts/...",
        "content_type": "image/png"
      }
    ]
  }
}
```

Use the returned Sume media URLs. Raw provider URLs are not part of the public
result contract.

## Next

- [Video 1.0](/models/video) for motion from prompts or first frames
- [Jobs and results](/workflows/jobs-and-results) for modes, cancellation, and events
- [Media inputs](/workflows/asset-library) for HTTPS URL rules
- [Recipes](/api/cookbook) for short copy-paste flows