API reference
Generate an image
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 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. |
Body
| Name | Type | Required | Description |
|---|---|---|---|
model | string | Yes | An id from List image 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. |
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
Generate an image
POST /v1/image-router/generate
Required
Response
202 Accepted
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. |