---
title: Generate an image
description: Create an image job with any model on the Image Router.
---
`POST` `/v1/image-router/generate`

**Host** `https://api.open.sume.com` · **Auth** API key

Starts an image job with the model you name and returns at once with the job id and the URLs to follow. The job runs on its own; poll [Get job status](/docs/reference/jobs/status) or set a webhook.

## Request

### Headers

| Header | Type | Required | Description |
|---|---|---|---|
| `Authorization` | string | Yes | `Bearer <key>`. Or send `x-api-key`. |
| `Content-Type` | string | Yes | `application/json` |
| `Idempotency-Key` | string | No | 1–255 printable ASCII. Makes a retry return the original job. See [Idempotency](/docs/idempotency). |

### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `model` | string | Yes | An id from [List image models](/docs/reference/images/list-models), such as `gpt-image-2` or `nano-banana-pro`. |
| `prompt` | string | Yes | What to make. |
| `image_urls` | string[] | No | 1–16 HTTPS images to edit or follow. Text-only models reject it. |
| `aspect_ratio` | string | No | One the model lists, such as `1:1`, `16:9`, `9:16`, `4:5`. `auto` follows an input image. |
| `image_size` | string or object | No | A named preset, `WIDTHxHEIGHT`, or `{width, height}`. Wins over `aspect_ratio`. |
| `quality` | string | No | Model-specific. `gpt-image-2`: `low`, `medium`, `high`. |
| `resolution` | string | No | Model-specific, such as `1K`, `2K`, `4K` or `1080p`. |
| `num_images` | integer | No | 1–4 images in one job. Default 1. |
| `output_format` | string | No | `png`, `jpeg` or `webp`, where the model lists it. |
| `mask_url` | string | No | An edit mask, on models that take one. |
| `mode` | string | No | `async` (default), `webhook`, `sync` or `subscribe`. See [How the API works](/docs/how-it-works). |
| `webhook_url` | string | No | Public HTTPS URL for the terminal callback. Used with `mode: "webhook"`. |
| `wait_timeout_seconds` | integer | No | 0–30. How long `sync` / `subscribe` waits before answering. |
| `metadata` | object | No | Your own key-value data, stored on the job. Not sent to the model. |

## Example

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

## Response

`202 Accepted`

```json
{
  "data": {
    "request_id": "job_7513b52d-3669-4ffe-b317-8b02000715eb",
    "job": {
      "id": "job_7513b52d-3669-4ffe-b317-8b02000715eb",
      "type": "image_generation",
      "status": "queued",
      "model": "gpt-image-2",
      "idempotency_key": "9816bc88-9791-43a1-86c2-876dc7c544e8",
      "communication_mode": "async",
      "created_at": "2026-10-14T23:01:52.075Z",
      "started_at": null,
      "completed_at": null,
      "result": null,
      "error": null,
      "input": {
        "prompt": "A ceramic coffee cup on a wooden table, soft morning light",
        "quality": "low",
        "aspect_ratio": "1:1"
      }
    },
    "status_url": "https://api.open.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/status",
    "result_url": "https://api.open.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/result",
    "events_url": "https://api.open.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/events",
    "cancel_url": null,
    "cancelable": false,
    "next_action": "poll_status",
    "next_poll_after_seconds": 2,
    "recommended_poll_interval_seconds": 2,
    "result_ready": false,
    "terminal": false,
    "idempotency_hit": false
  }
}
```

## Errors

| Status | `code` | When |
|---|---|---|
| 400 | `invalid_request` | A field is missing, unknown for the model, or out of range. |
| 400 | `concurrency_limit_reached` | Your workspace is at its jobs-in-flight cap. |
| 401 | `unauthorized` | No key, or the key is wrong or revoked. |
| 402 | `insufficient_funds` | Your balance cannot cover the price. `details` has `required_usd` and `available_usd`. |
| 409 | `idempotency_conflict` | The `Idempotency-Key` was used for a different request. |
| 429 | `rate_limited` | Too many requests for your key in this window. |
| 503 | `database_busy` | A short overload. Retry after `retry-after`. |

[All error codes](/docs/errors)

## Related

- [List image models](/docs/reference/images/list-models)
- [Get job status](/docs/reference/jobs/status)
- [Input media](/docs/input-media)
- [Estimate a price](/docs/reference/catalog/estimate)