---
title: Image 1.0
description: Retiring soon. Compatibility alias for Image Router Auto.
---

**Retiring soon.** Image 1.0 is a compatibility alias for [Image Router Auto](/models/images).
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:

```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 | 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

<!-- 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