Generate

Images

One endpoint for every image model: text to image, edits with reference images, several images per job.

POSThttps://api.sume.com/v1/image-router/generate

Request

Send Authorization and Content-Type: application/json, and an Idempotency-Key (1–255 printable ASCII) so a retry returns the same job. Fields a model does not take are refused with 400; each model's row in Models lists what it accepts.

Name	Type	Required	Description
`model`	string	Yes	Model id, such as `gpt-image-2` or `nano-banana-pro`.
`prompt`	string	Yes	What to make, or what to change in an edit.
`image_urls`	string[]	No	1–16 public HTTPS images to edit or follow. Text-only models refuse it.
`aspect_ratio`	string	No	One the model lists, such as `1:1`, `16:9`, `9:16`; `auto` follows the input image.
`image_size`	string \| object	No	A preset, `WIDTHxHEIGHT` or `{ width, height }`. Wins over `aspect_ratio`.
`quality`	string	No	Model-specific, for example `low`, `medium`, `high`.
`resolution`	string	No	Model-specific, for example `1K`, `2K`, `4K`.
`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	Edit mask, on models that take one.
`mode`	string	No	`async` (default), `webhook`, `sync` or `subscribe`. See Jobs.
`webhook_url`	string	No	Public HTTPS URL called when the job ends, with `mode: "webhook"`.
`wait_timeout_seconds`	integer	No	0–30. How long `sync` waits before answering.
`metadata`	object	No	Your own key-value data, stored on the job and never sent to the model.

Example

curl -X POST https://api.sume.com/v1/image-router/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A ceramic coffee cup on a wooden table, soft morning light",
    "quality": "low",
    "aspect_ratio": "1:1"
  }'

Edit an image

Pass the source in image_urls on a model that edits, such as gpt-image-2 or nano-banana-pro. A local file goes up first through File uploads.

cURL

curl -X POST https://api.sume.com/v1/image-router/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "Make the cup cobalt blue, keep everything else the same",
    "image_urls": ["https://media.sume.com/assets/asset_6f1d0c2b/source.png"]
  }'

Response

202 Accepted with the job and the URLs to follow. Poll status_url, then read result_url; each image is one artifact.

202 Accepted

{
  "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",
      "created_at": "2026-10-21T02:31:52.075Z",
      "result": null,
      "error": null
    },
    "status_url": "https://api.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/status",
    "result_url": "https://api.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/result",
    "events_url": "https://api.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,
    "terminal": false,
    "idempotency_hit": false
  }
}

Errors

Status	code	When
400	`invalid_request`	A field is missing, unknown for the model or out of range.
401	`unauthorized`	No key, or the key is wrong or revoked.
402	`insufficient_funds`	The workspace balance does not cover the price.
409	`idempotency_conflict`	The Idempotency-Key was used for a different request.
429	`queue_full`	The workspace has as many jobs in flight as it may.
429	`rate_limited`	Too many requests for this key right now.

Generate

Images

One endpoint for every image model: text to image, edits with reference images, several images per job.

POSThttps://api.sume.com/v1/image-router/generate

Request

Name	Type	Required	Description
`model`	string	Yes	Model id, such as `gpt-image-2` or `nano-banana-pro`.
`prompt`	string	Yes	What to make, or what to change in an edit.
`image_urls`	string[]	No	1–16 public HTTPS images to edit or follow. Text-only models refuse it.
`aspect_ratio`	string	No	One the model lists, such as `1:1`, `16:9`, `9:16`; `auto` follows the input image.
`image_size`	string \| object	No	A preset, `WIDTHxHEIGHT` or `{ width, height }`. Wins over `aspect_ratio`.
`quality`	string	No	Model-specific, for example `low`, `medium`, `high`.
`resolution`	string	No	Model-specific, for example `1K`, `2K`, `4K`.
`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	Edit mask, on models that take one.
`mode`	string	No	`async` (default), `webhook`, `sync` or `subscribe`. See Jobs.
`webhook_url`	string	No	Public HTTPS URL called when the job ends, with `mode: "webhook"`.
`wait_timeout_seconds`	integer	No	0–30. How long `sync` waits before answering.
`metadata`	object	No	Your own key-value data, stored on the job and never sent to the model.

Example

curl -X POST https://api.sume.com/v1/image-router/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A ceramic coffee cup on a wooden table, soft morning light",
    "quality": "low",
    "aspect_ratio": "1:1"
  }'

Edit an image

Pass the source in image_urls on a model that edits, such as gpt-image-2 or nano-banana-pro. A local file goes up first through File uploads.

cURL

curl -X POST https://api.sume.com/v1/image-router/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "Make the cup cobalt blue, keep everything else the same",
    "image_urls": ["https://media.sume.com/assets/asset_6f1d0c2b/source.png"]
  }'

Response

202 Accepted with the job and the URLs to follow. Poll status_url, then read result_url; each image is one artifact.

202 Accepted

{
  "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",
      "created_at": "2026-10-21T02:31:52.075Z",
      "result": null,
      "error": null
    },
    "status_url": "https://api.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/status",
    "result_url": "https://api.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/result",
    "events_url": "https://api.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,
    "terminal": false,
    "idempotency_hit": false
  }
}

Errors

Status	code	When
400	`invalid_request`	A field is missing, unknown for the model or out of range.
401	`unauthorized`	No key, or the key is wrong or revoked.
402	`insufficient_funds`	The workspace balance does not cover the price.
409	`idempotency_conflict`	The Idempotency-Key was used for a different request.
429	`queue_full`	The workspace has as many jobs in flight as it may.
429	`rate_limited`	Too many requests for this key right now.

Images

Related

Images

Related