Seedream 5.0 Pro

Generate 1–4 images from a prompt, optionally guided by reference images, with optional background removal, billed per image.

Seedream 5.0 Pro (product seedream) generates images from a prompt, optionally guided by up to 10 reference images, and can remove the background. One task makes 1–4 images, billed per image.

Create a task

POSThttps://api.nanoapi.ai/v1/tasks

Use the shared create endpoint with model: "seedream-5.0-pro". It usually responds in under 1 second, and the cost of num_outputs images is frozen within a few seconds. Get the result once the task has finished.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <API key>`, see Authentication.
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	A unique string for every new task, ideally a UUID (1–255 characters). See Preventing duplicate tasks.

Body

Parameter	Type	Required	Description
`model`	`string`	Yes	`seedream-5.0-pro`.
`prompt`	`string`	Yes	What to generate, at most 8000 characters. Refer to the reference images as `@Image1`, `@Image2`…, see Referring to images.
`image_urls`	`string[]`	No	Up to 10 reference images; leave it out to generate from the prompt alone. See Media.
`resolution`	`string`	Yes	`1k`, `1.5k` or `2k`. Sets the price.
`aspect_ratio`	`string`	Yes	`1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3` or `21:9`. There's no `auto`: with reference images, pick the ratio you want.
`remove_bg`	`boolean`	No	`true` removes the background and gives a PNG with a transparent background (reference images work too); off when left out.
`num_outputs`	`integer`	Yes	How many images, 1–4. All of them are frozen; only the ones generated are charged, see Pricing.
`webhook_url`	`string`	No	Notified when the task succeeds or fails: `https`, up to 2048 characters, not a private, loopback or reserved address. See Webhooks.

Any other parameter, such as the other image models' quality or seed, returns 400 invalid_request, see Errors.

One 16:9 image at 2k:

curl https://api.nanoapi.ai/v1/tasks \
  -H "Authorization: Bearer $NANOAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6c1d8e3f-9a2b-4d5c-8e7f-0b4a3c2d1e96" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "A lighthouse at dusk, cinematic lighting",
    "resolution": "2k",
    "aspect_ratio": "16:9",
    "num_outputs": 1
  }'

Response: 200 OK. data is the newly created task, with only these fields; each one is described in Create a task: Response. Keep data.id to get the result. The task can still fail after it's created (for example if your balance can't cover it), so go by what retrieving the task or the webhook tells you.

{
  "code": 200,
  "message": "success",
  "data": {
    "object": "task",
    "id": "tk_01jbh6q9e4z7x0d5p8s1y3g6u9",
    "model": "seedream-5.0-pro",
    "status": "queued",
    "error": null,
    "created_at": "2026-11-01T08:30:00Z"
  }
}

Get the result

As a rough guide (generation only, not counting the queue, plus a few seconds to store the files; slower when the provider is busy): about 30 seconds at 1k, 30–45 seconds at 1.5k and 50 seconds at 2k. The images of a task are generated in parallel, so several take about as long as one. Once the task has finished (succeeded or failed), get the result either way:

Webhook (recommended in production): if you passed webhook_url, the full task is pushed to it once when the task finishes. See Webhooks.
Polling: call GET /v1/tasks/{task_id} with data.id at most once every 15 seconds until status is succeeded or failed. Check several tasks at once with ids in List tasks.

The request above, once it has succeeded (other fields left out):

{
  "status": "succeeded",
  "input": {
    "prompt": "A lighthouse at dusk, cinematic lighting",
    "resolution": "2k",
    "aspect_ratio": "16:9"
  },
  "num_outputs": 1,
  "outputs": [
    {
      "index": 0,
      "type": "image",
      "url": "https://cdn.nanoapi.ai/h/tk_01jbh6q9e4z7x0d5p8s1y3g6u9_1_1793521800.png",
      "preview_url": "https://cdn.nanoapi.ai/h/tk_01jbh6q9e4z7x0d5p8s1y3g6u9_1_1793521800_compressed.jpg"
    }
  ],
  "billing": {
    "currency": "USD",
    "frozen": "…", // 1 × the 2k price per image
    "charged": "…", // the same
    "refunded": "0.00",
    "billed_seconds": null
  }
}

Field	Seedream 5.0 Pro
`outputs`	One item per generated image, at most `num_outputs`.
`outputs[].type`	`image`.
`outputs[].url`	The original image, a PNG; with `remove_bg: true`, the background stays transparent. Use it to download or show the image full size; files are large (roughly 1–2 MB at 1k).
`outputs[].preview_url`	A JPEG preview, at most 1024 pixels on the long side (smaller images aren't enlarged), with any transparency shown as white. Use it for lists and thumbnails. `null` if it couldn't be made.
`billing.billed_seconds`	Always `null`: images are billed per image.
`input`	The parameters you sent; the optional `image_urls` and `remove_bg` only if you sent them.

On failure the frozen amount is returned in full and the reason is in data.error.type, see Errors. Every field is described in The task object.

Image sizes

Width × height in pixels.

`aspect_ratio`	1k	1.5k	2k
`1:1`	1024×1024	1536×1536	2048×2048
`4:3`	1168×880	1760×1328	2352×1760
`3:4`	880×1168	1328×1760	1760×2352
`3:2`	1248×832	1872×1248	2496×1664
`2:3`	832×1248	1248×1872	1664×2496
`16:9`	1360×768	2048×1152	2720×1536
`9:16`	768×1360	1152×2048	1536×2720
`21:9`	1552×656	2336×992	3120×1328

Fewer images than requested

Each image is generated on its own. If some can't be made (for example because moderation blocked them), the task still succeeded: outputs only has the images that were generated, fewer than num_outputs. Only those are charged and the rest of the frozen amount is returned (billing.refunded). The task fails only when no image could be generated, and then everything frozen is returned: if at least one of them was blocked by moderation, the reason is content_policy (not every image has to be blocked, the others may have failed for other reasons), otherwise usually generation_failed. outputs[].index numbers the generated images from 0 without gaps, so when there are fewer it doesn't match the position in your request: don't use it to pair images with anything.

Media

Reference images are passed in image_urls as public http(s) URLs. There's no upload endpoint: host the files yourself. URLs are at most 4096 characters, must download directly and can't point to localhost or private, loopback or reserved addresses.

	Reference images (`image_urls`)
Count	0–10 (`limits.max_reference_images` in `GET /v1/products`)
Formats	JPEG, PNG, WebP, AVIF, GIF (the first frame), BMP and TIFF. HEIC / HEIF aren't supported: iPhone photos are HEIC by default, so convert them to JPEG first.
Transparency	A transparent PNG is flattened onto white before it's used.
If there's a problem	Read only when generation runs, after the cost was frozen: if an image can't be downloaded or its format isn't supported, the task fails with `invalid_media` and the frozen amount is returned in full.

Keep every link reachable until the task finishes, including links that expire.

Referring to images in the prompt

In `prompt`	Refers to
`@Image1`, `@Image2`, …	The images in `image_urls`, in order.

A reference beyond the images you sent (for example @Image2 with one image, or any @Image without image_urls) returns 400 invalid_request with param "prompt", and no task is created.
An @ right after a letter, digit or dot isn't a reference, so an email address such as bob@image2go.com in the prompt is fine.

Pricing

frozen  = price per image of the resolution × num_outputs
charged = price per image of the resolution × images generated

Loading the current prices…

Only resolution changes the price. aspect_ratio, remove_bg and reference images don't.
The cost of all num_outputs images is frozen within a few seconds of creating the task. When it succeeds, each generated image is charged and the rest is returned, see Fewer images than requested; when it fails, all of it is returned.

Example: the request above (2k, one image) freezes 1 × the 2k price per image and is charged the same when it succeeds. With num_outputs 3 it would freeze 3 × that price, and if only two images were generated, 2 × the price would be charged and the third returned. How freezing and charging work in general: Billing.

The price is known from the request, so you can show it before submitting: read the current prices from GET /v1/products (one prices row per resolution). Prices change, so don't hard-code them; billing.frozen on the retrieved task is what counts.

Errors

Errors and failure reasons specific to this model. Every error of the create endpoint: Create a task → Errors; every failure reason: Failure reasons.

Create request errors: the request fails with an HTTP error and no task is created. param names the parameter.

Status	`error.type`	When	What to do
`400`	`invalid_request`	A required parameter is missing (`Field required`, `param` names it) or `prompt` is empty (`prompt is required`).	Send every required parameter, see Create a task.
`400`	`invalid_request`	The prompt refers to an image you didn't send, with `param` `"prompt"` (for example `prompt references @Image2, but image_urls has 1 image: use @Image1`).	Fix the reference, or add the image to `image_urls`.
`400`	`invalid_request`	`resolution` or `aspect_ratio` isn't one of the values above (`auto` included, for example `Input should be '1:1', '4:3', '3:4', '16:9', '9:16', '3:2', '2:3' or '21:9' for seedream-5.0-pro`), `num_outputs` isn't 1–4, or `image_urls` has more than 10 images.	Use an allowed value.
`400`	`invalid_request`	A parameter this model doesn't take: another image model's (`quality`, `variant`, `background`, `thinking_level`, `enable_web_search`, `enable_image_search`, `seed`) or a video model's (`Extra inputs are not permitted`).	Remove it.

Other errors of the create endpoint (401, 402, 429 and so on): Create a task → Errors.

Task failures: the create request succeeded (200) and the task later turned failed. There's no HTTP status: the reason is the task's error.type, from retrieving the task or the webhook.

`error.type`	When	What to do
`insufficient_balance`	Your available balance can't cover `num_outputs` × the price per image. Within a few seconds of creating the task, nothing frozen.	Top up, or ask for fewer images, then create the task again.
`spend_limit_exceeded`	This task's cost would go over one of the key's spend limits. Within a few seconds of creating the task, nothing frozen.	Raise the limit in Console → API keys, or wait for it to reset, then create the task again.
`invalid_media`	A reference image can't be downloaded or read (for example a HEIC photo, or a corrupt file). Found when generation runs, after the cost was frozen: all of it is returned.	Replace the image `error.message` points to (convert HEIC to JPEG) and create the task again.
`content_policy`	No image could be generated, and at least one was blocked because the prompt or a reference image breaks the content policy (not necessarily every one). If only some images are blocked, the task succeeds with the others instead, see Fewer images than requested.	Resubmitting it as is fails again: change the prompt or the images.
`generation_failed`	No image could be generated.	Create it again later, or change the prompt or images.
`queue_timeout` / `internal_error`	Not started within 30 minutes / an error on our side.	Create it again later.

Every failed task has its frozen amount returned in full and billing.charged "0.00".

Seedream 5.0 Pro (product seedream) generates images from a prompt, optionally guided by up to 10 reference images, and can remove the background. One task makes 1–4 images, billed per image.

Create a task

POSThttps://api.nanoapi.ai/v1/tasks

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <API key>`, see Authentication.
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	A unique string for every new task, ideally a UUID (1–255 characters). See Preventing duplicate tasks.

Body

Parameter	Type	Required	Description
`model`	`string`	Yes	`seedream-5.0-pro`.
`prompt`	`string`	Yes	What to generate, at most 8000 characters. Refer to the reference images as `@Image1`, `@Image2`…, see Referring to images.
`image_urls`	`string[]`	No	Up to 10 reference images; leave it out to generate from the prompt alone. See Media.
`resolution`	`string`	Yes	`1k`, `1.5k` or `2k`. Sets the price.
`aspect_ratio`	`string`	Yes	`1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3` or `21:9`. There's no `auto`: with reference images, pick the ratio you want.
`remove_bg`	`boolean`	No	`true` removes the background and gives a PNG with a transparent background (reference images work too); off when left out.
`num_outputs`	`integer`	Yes	How many images, 1–4. All of them are frozen; only the ones generated are charged, see Pricing.
`webhook_url`	`string`	No	Notified when the task succeeds or fails: `https`, up to 2048 characters, not a private, loopback or reserved address. See Webhooks.

Any other parameter, such as the other image models' quality or seed, returns 400 invalid_request, see Errors.

One 16:9 image at 2k:

curl https://api.nanoapi.ai/v1/tasks \
  -H "Authorization: Bearer $NANOAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6c1d8e3f-9a2b-4d5c-8e7f-0b4a3c2d1e96" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "A lighthouse at dusk, cinematic lighting",
    "resolution": "2k",
    "aspect_ratio": "16:9",
    "num_outputs": 1
  }'

{
  "code": 200,
  "message": "success",
  "data": {
    "object": "task",
    "id": "tk_01jbh6q9e4z7x0d5p8s1y3g6u9",
    "model": "seedream-5.0-pro",
    "status": "queued",
    "error": null,
    "created_at": "2026-11-01T08:30:00Z"
  }
}

Get the result

Webhook (recommended in production): if you passed webhook_url, the full task is pushed to it once when the task finishes. See Webhooks.
Polling: call GET /v1/tasks/{task_id} with data.id at most once every 15 seconds until status is succeeded or failed. Check several tasks at once with ids in List tasks.

The request above, once it has succeeded (other fields left out):

{
  "status": "succeeded",
  "input": {
    "prompt": "A lighthouse at dusk, cinematic lighting",
    "resolution": "2k",
    "aspect_ratio": "16:9"
  },
  "num_outputs": 1,
  "outputs": [
    {
      "index": 0,
      "type": "image",
      "url": "https://cdn.nanoapi.ai/h/tk_01jbh6q9e4z7x0d5p8s1y3g6u9_1_1793521800.png",
      "preview_url": "https://cdn.nanoapi.ai/h/tk_01jbh6q9e4z7x0d5p8s1y3g6u9_1_1793521800_compressed.jpg"
    }
  ],
  "billing": {
    "currency": "USD",
    "frozen": "…", // 1 × the 2k price per image
    "charged": "…", // the same
    "refunded": "0.00",
    "billed_seconds": null
  }
}

Field	Seedream 5.0 Pro
`outputs`	One item per generated image, at most `num_outputs`.
`outputs[].type`	`image`.
`outputs[].url`	The original image, a PNG; with `remove_bg: true`, the background stays transparent. Use it to download or show the image full size; files are large (roughly 1–2 MB at 1k).
`outputs[].preview_url`	A JPEG preview, at most 1024 pixels on the long side (smaller images aren't enlarged), with any transparency shown as white. Use it for lists and thumbnails. `null` if it couldn't be made.
`billing.billed_seconds`	Always `null`: images are billed per image.
`input`	The parameters you sent; the optional `image_urls` and `remove_bg` only if you sent them.

On failure the frozen amount is returned in full and the reason is in data.error.type, see Errors. Every field is described in The task object.

Image sizes

Width × height in pixels.

`aspect_ratio`	1k	1.5k	2k
`1:1`	1024×1024	1536×1536	2048×2048
`4:3`	1168×880	1760×1328	2352×1760
`3:4`	880×1168	1328×1760	1760×2352
`3:2`	1248×832	1872×1248	2496×1664
`2:3`	832×1248	1248×1872	1664×2496
`16:9`	1360×768	2048×1152	2720×1536
`9:16`	768×1360	1152×2048	1536×2720
`21:9`	1552×656	2336×992	3120×1328

Fewer images than requested

Media

	Reference images (`image_urls`)
Count	0–10 (`limits.max_reference_images` in `GET /v1/products`)
Formats	JPEG, PNG, WebP, AVIF, GIF (the first frame), BMP and TIFF. HEIC / HEIF aren't supported: iPhone photos are HEIC by default, so convert them to JPEG first.
Transparency	A transparent PNG is flattened onto white before it's used.
If there's a problem	Read only when generation runs, after the cost was frozen: if an image can't be downloaded or its format isn't supported, the task fails with `invalid_media` and the frozen amount is returned in full.

Keep every link reachable until the task finishes, including links that expire.

Referring to images in the prompt

In `prompt`	Refers to
`@Image1`, `@Image2`, …	The images in `image_urls`, in order.

A reference beyond the images you sent (for example @Image2 with one image, or any @Image without image_urls) returns 400 invalid_request with param "prompt", and no task is created.
An @ right after a letter, digit or dot isn't a reference, so an email address such as bob@image2go.com in the prompt is fine.

Pricing

frozen  = price per image of the resolution × num_outputs
charged = price per image of the resolution × images generated

Loading the current prices…

Only resolution changes the price. aspect_ratio, remove_bg and reference images don't.
The cost of all num_outputs images is frozen within a few seconds of creating the task. When it succeeds, each generated image is charged and the rest is returned, see Fewer images than requested; when it fails, all of it is returned.

Errors

Errors and failure reasons specific to this model. Every error of the create endpoint: Create a task → Errors; every failure reason: Failure reasons.

Create request errors: the request fails with an HTTP error and no task is created. param names the parameter.

Status	`error.type`	When	What to do
`400`	`invalid_request`	A required parameter is missing (`Field required`, `param` names it) or `prompt` is empty (`prompt is required`).	Send every required parameter, see Create a task.
`400`	`invalid_request`	The prompt refers to an image you didn't send, with `param` `"prompt"` (for example `prompt references @Image2, but image_urls has 1 image: use @Image1`).	Fix the reference, or add the image to `image_urls`.
`400`	`invalid_request`	`resolution` or `aspect_ratio` isn't one of the values above (`auto` included, for example `Input should be '1:1', '4:3', '3:4', '16:9', '9:16', '3:2', '2:3' or '21:9' for seedream-5.0-pro`), `num_outputs` isn't 1–4, or `image_urls` has more than 10 images.	Use an allowed value.
`400`	`invalid_request`	A parameter this model doesn't take: another image model's (`quality`, `variant`, `background`, `thinking_level`, `enable_web_search`, `enable_image_search`, `seed`) or a video model's (`Extra inputs are not permitted`).	Remove it.

Other errors of the create endpoint (401, 402, 429 and so on): Create a task → Errors.

Task failures: the create request succeeded (200) and the task later turned failed. There's no HTTP status: the reason is the task's error.type, from retrieving the task or the webhook.

`error.type`	When	What to do
`insufficient_balance`	Your available balance can't cover `num_outputs` × the price per image. Within a few seconds of creating the task, nothing frozen.	Top up, or ask for fewer images, then create the task again.
`spend_limit_exceeded`	This task's cost would go over one of the key's spend limits. Within a few seconds of creating the task, nothing frozen.	Raise the limit in Console → API keys, or wait for it to reset, then create the task again.
`invalid_media`	A reference image can't be downloaded or read (for example a HEIC photo, or a corrupt file). Found when generation runs, after the cost was frozen: all of it is returned.	Replace the image `error.message` points to (convert HEIC to JPEG) and create the task again.
`content_policy`	No image could be generated, and at least one was blocked because the prompt or a reference image breaks the content policy (not necessarily every one). If only some images are blocked, the task succeeds with the others instead, see Fewer images than requested.	Resubmitting it as is fails again: change the prompt or the images.
`generation_failed`	No image could be generated.	Create it again later, or change the prompt or images.
`queue_timeout` / `internal_error`	Not started within 30 minutes / an error on our side.	Create it again later.

Every failed task has its frozen amount returned in full and billing.charged "0.00".

Seedream 5.0 Pro

Create a task

Get the result

Image sizes

Fewer images than requested

Media

Referring to images in the prompt

Pricing

Errors

Table of Contents

Seedream 5.0 Pro

Create a task

Get the result

Image sizes

Fewer images than requested

Media

Referring to images in the prompt

Pricing

Errors

Table of Contents