Seedream 5.0 Pro API, Seedream 5.0 Flash API, Seedream 5.0 Lite API, Seedream 4.5 API, Seedream 4.0 API: Pricing, Documentation

Seedream 5 Pro API Documentation

• Premium retouching: background swaps, relighting and cleanup at the highest quality tier.
• Photorealistic object insertion: composite products or elements seamlessly into scenes.
• Multi-reference composition: combine up to 10 reference images (e.g. place a product into a new setting).
• Brand-consistent variations: produce style-matched edits of hero imagery for campaigns.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "seedream-5-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedream-5-pro",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "seedream-5-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-pro",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

• terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
• sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
• Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
• Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
• HTTPS required — plain http:// URLs are rejected.

Request Parameters - Seedream 5 Pro Edit generate request

Content Item Types & Limits

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: $0.035"
}

// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'seedream-5-pro' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "seedream-5-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-pro",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/seedream-5-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "seedream-5-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedream-5-pro",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-04-17T11:41:07.503Z",
  "updated_at": "2026-04-17T11:42:15.000Z",
  "completed_at": "2026-04-17T11:42:15.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

1. Send a generate request to the API endpoint
2. Save the request_id from the response
3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
4. When status is "COMPLETED", download from output.media_url

Tip: Use X-Webhook-URL header to get a callback instead of polling.

Seedream 5 Pro API Documentation

• High-fidelity hero images: landing pages, campaigns and key art where detail matters most.
• Photorealistic product renders: packaging mockups and premium product visuals.
• Editorial illustration: magazine-quality art for articles and features.
• Print-ready visuals: 2K output suitable for high-quality print and large display.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "seedream-5-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedream-5-pro",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "seedream-5-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-pro",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

• terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
• sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
• Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
• Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
• HTTPS required — plain http:// URLs are rejected.

Request Parameters - Seedream 5 Pro Text to Image generate request

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: $0.035"
}

// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'seedream-5-pro' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "seedream-5-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-pro",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/seedream-5-pro_019d9b3e-9e95-75e3-7533-a5f1149cd9f94"

{
  "request_id": "seedream-5-pro_019d9b3e-9e95-75e3-7533-a5f1149cd9f94",
  "status": "COMPLETED",
  "model_id": "seedream-5-pro",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-pro_019d9b3e-9e95-75e3-7533-a5f1149cd9f94/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-04-17T11:41:06.171Z",
  "updated_at": "2026-04-17T11:41:57.000Z",
  "completed_at": "2026-04-17T11:41:57.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

1. Send a generate request to the API endpoint
2. Save the request_id from the response
3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
4. When status is "COMPLETED", download from output.media_url

Tip: Use X-Webhook-URL header to get a callback instead of polling.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "seedream-5-0-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedream-5-0-pro-layerize",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-0-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "seedream-5-0-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-0-pro-layerize",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

• terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
• sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
• Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
• Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
• HTTPS required — plain http:// URLs are rejected.

Request Parameters - Seedream 5.0 Pro Layerize generate request

The response is many images, not one. A call returns a base image plus up to 16 separated layers — 2 to 17 in total. media_url is an array in that order, and a parallel layers array carries the metadata for each one: index, url, z_index, and (on every layer except the base) name, description and bounding_box. layers[i] always describes media_url[i].

The base layer is z_index 0 and is opaque; it carries no name, description or bounding_box, because those fields only describe an extracted element. Every other layer is a transparent PNG. Layers are ordered bottom to top by z_index, so drawing them in array order recomposes the image.

bounding_box gives the layer's position in the base image's coordinate system. It is not the dimensions of the returned PNG — a layer is delivered at its own natural size, which may differ from its box. Use the box to place the layer, not to size it.

Built for finished, composed images — product shots, posters, UI mockups, scenes with distinct objects. An image with nothing separable comes back as a base plus very few layers, and is billed for what it produced.

Pricing: billed per generated layer, at a rate set by the pixel area of the generated base layer: $0.03375 per layer under 1536×1536, $0.0675 per layer at or above it. A 10-layer result from a 1024×1024 base costs $0.3375. Because the layer count is decided by the model, the exact cost is not known before the call — a generous amount is reserved on submit and released down to the real charge when the job completes, so you are only ever charged for the layers you actually receive.

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: $0.035"
}

// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'seedream-5-0-pro-layerize' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "seedream-5-0-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-0-pro-layerize",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/seedream-5-0-pro_019d9b3e-9e95-75e3-7533-a5f1149cd9f94"

{
  "request_id": "seedream-5-0-pro_019d9b3e-9e95-75e3-7533-a5f1149cd9f94",
  "status": "COMPLETED",
  "model_id": "seedream-5-0-pro-layerize",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-0-pro_019d9b3e-9e95-75e3-7533-a5f1149cd9f94/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-04-17T11:41:06.171Z",
  "updated_at": "2026-04-17T11:41:57.000Z",
  "completed_at": "2026-04-17T11:41:57.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

1. Send a generate request to the API endpoint
2. Save the request_id from the response
3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
4. When status is "COMPLETED", download from output.media_url

Tip: Use X-Webhook-URL header to get a callback instead of polling.

Seedream 5 Flash API Documentation

• Quick retouching: background swaps, relighting and cleanup at low cost.
• Object insertion and replacement: place products or elements into an existing scene.
• Multi-reference composition: combine up to 10 reference images (e.g. the outfit from one image on the person in another).
• Variations at volume: many style-consistent edits of the same image for testing and campaigns.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "seedream-5-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedream-5-flash",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "seedream-5-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-flash",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

• terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
• sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
• Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
• Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
• HTTPS required — plain http:// URLs are rejected.

Request Parameters - Seedream 5 Flash Edit generate request

Content Item Types & Limits

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: (the price of this request)"
}

// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'seedream-5-flash' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "seedream-5-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-flash",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/seedream-5-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "seedream-5-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedream-5-flash",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-04-17T11:41:07.503Z",
  "updated_at": "2026-04-17T11:42:15.000Z",
  "completed_at": "2026-04-17T11:42:15.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

1. Send a generate request to the API endpoint
2. Save the request_id from the response
3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
4. When status is "COMPLETED", download from output.media_url

Tip: Use X-Webhook-URL header to get a callback instead of polling.

Seedream 5 Flash API Documentation

• Fast drafts and iteration: explore many prompt variations quickly and cheaply before committing to a final render.
• High-volume content: social posts, thumbnails and catalog imagery at scale.
• Product and marketing visuals: clean product shots and campaign variants on a budget.
• Previews: try layouts and concepts before a Seedream 5 Flash final.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "seedream-5-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedream-5-flash",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "seedream-5-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-flash",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

• terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
• sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
• Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
• Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
• HTTPS required — plain http:// URLs are rejected.

Request Parameters - Seedream 5 Flash Text to Image generate request

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: (the price of this request)"
}

// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'seedream-5-flash' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "seedream-5-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-flash",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/seedream-5-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "seedream-5-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedream-5-flash",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-04-17T11:41:06.171Z",
  "updated_at": "2026-04-17T11:41:57.000Z",
  "completed_at": "2026-04-17T11:41:57.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

1. Send a generate request to the API endpoint
2. Save the request_id from the response
3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
4. When status is "COMPLETED", download from output.media_url

Tip: Use X-Webhook-URL header to get a callback instead of polling.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "seedream-5-0-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedream-5-0-flash-layerize",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-0-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "seedream-5-0-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-0-flash-layerize",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

• terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
• sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
• Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
• Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
• HTTPS required — plain http:// URLs are rejected.

Request Parameters - Seedream 5.0 Flash Layerize generate request

The response is many images, not one. A call returns a base image plus up to 16 separated layers — 1 to 17 in total. media_url is an array in that order, and a parallel layers array carries the metadata for each one: index, url, z_index, and (on every layer except the base) name, description and bounding_box. layers[i] always describes media_url[i].

The base layer is z_index 0 and is opaque; it carries no name, description or bounding_box, because those fields only describe an extracted element. Every other layer is a transparent PNG. Layers are ordered bottom to top by z_index, so drawing them in array order recomposes the image.

bounding_box gives the layer's position in the base image's coordinate system. It is not the dimensions of the returned PNG — a layer is delivered at its own natural size, which may differ from its box. Use the box to place the layer, not to size it.

Built for finished, composed images — product shots, posters, UI mockups, scenes with distinct objects. An image with nothing separable comes back as a base plus very few layers, and is billed for what it produced.

Pricing: billed per output image — the base image and each separated layer count as one image each — at one flat rate at every image size; the current rate is in the pricing panel on this page. Because the layer count is decided by the model, the exact cost is not known before the call — the price of the maximum (17 images) is reserved on submit and released down to the real charge when the job completes, so you are only ever charged for the images you actually receive.

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: (the price of this request)"
}

// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'seedream-5-0-flash-layerize' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "seedream-5-0-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-0-flash-layerize",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/seedream-5-0-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "seedream-5-0-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedream-5-0-flash-layerize",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-0-flash_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-04-17T11:41:06.171Z",
  "updated_at": "2026-04-17T11:41:57.000Z",
  "completed_at": "2026-04-17T11:41:57.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

1. Send a generate request to the API endpoint
2. Save the request_id from the response
3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
4. When status is "COMPLETED", download from output.media_url

Tip: Use X-Webhook-URL header to get a callback instead of polling.

Seedream 5 Lite API Documentation

• Background replacement: swap or clean up backgrounds with one instruction.
• Add / remove objects: insert or erase elements described in plain text.
• Style transfer & relighting: restyle photos or change lighting and mood.
• Product variants: recolor or restyle a product shot for e-commerce listings.
• Multi-reference composition: blend up to 14 reference images into one coherent scene (refs + outputs ≤ 15).

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "seedream-5-lite_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedream-5-lite",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-lite_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "seedream-5-lite_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-lite",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

• terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
• sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
• Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
• Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
• HTTPS required — plain http:// URLs are rejected.

Request Parameters - Seedream 5 Lite Edit generate request

Content Item Types & Limits

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: $0.035"
}

// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'seedream-5-lite' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "seedream-5-lite_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-lite",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/seedream-5-lite_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "seedream-5-lite_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedream-5-lite",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-lite_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-04-17T11:41:07.503Z",
  "updated_at": "2026-04-17T11:42:15.000Z",
  "completed_at": "2026-04-17T11:42:15.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

1. Send a generate request to the API endpoint
2. Save the request_id from the response
3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
4. When status is "COMPLETED", download from output.media_url

Tip: Use X-Webhook-URL header to get a callback instead of polling.

Seedream 5 Lite API Documentation

• Rapid concept art & mood boards: iterate visual ideas quickly (~30–40s per image).
• Marketing & social creatives at scale: generate campaign and post imagery from copy.
• E-commerce visuals: product lifestyle shots and category imagery without a studio.
• Storyboards & keyframes: pre-visualise scenes for video and animation pipelines.
• Blog & hero illustrations: headers and section art generated from the article brief.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "seedream-5-lite_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedream-5-lite",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-lite_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "seedream-5-lite_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-lite",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

• terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
• sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
• Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
• Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
• HTTPS required — plain http:// URLs are rejected.

Request Parameters - Seedream 5 Lite Text to Image generate request

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: $0.035"
}

// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'seedream-5-lite' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "seedream-5-lite_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-lite",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/seedream-5-lite_019d9b3e-9e95-75e3-7533-a5f1149cd9f94"

{
  "request_id": "seedream-5-lite_019d9b3e-9e95-75e3-7533-a5f1149cd9f94",
  "status": "COMPLETED",
  "model_id": "seedream-5-lite",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-lite_019d9b3e-9e95-75e3-7533-a5f1149cd9f94/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-04-17T11:41:06.171Z",
  "updated_at": "2026-04-17T11:41:57.000Z",
  "completed_at": "2026-04-17T11:41:57.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

1. Send a generate request to the API endpoint
2. Save the request_id from the response
3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
4. When status is "COMPLETED", download from output.media_url

Tip: Use X-Webhook-URL header to get a callback instead of polling.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your request to receive a POST callback instead of polling.

X-Webhook-URL: https://your-server.com/webhook/callback

Request Parameters - Seedream 4.5 Image to Image (Edit Image)

Content Item Types & Limits

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: $0.04"
}

Error via Status/Webhook

{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "byteplus",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "byteplus",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1776429228529-aq8fsc3s5k7-1.jpg"
    ],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-04-17T12:33:13.000Z",
  "updated_at": "2026-04-17T12:33:13.000Z",
  "completed_at": "2026-04-17T12:33:13.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

1. Send a request to the API endpoint above
2. Save the request_id from the response
3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
4. When status is "COMPLETED", download from output.media_url

Tip: Use the X-Webhook-URL header to receive a callback instead of polling.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your request to receive a POST callback instead of polling.

X-Webhook-URL: https://your-server.com/webhook/callback

Request Parameters - Seedream 4.5 Text to Image

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: $0.04"
}

Error via Status/Webhook

{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "byteplus",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "byteplus",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1776429228529-aq8fsc3s5k7-1.jpg"
    ],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-04-17T12:33:13.000Z",
  "updated_at": "2026-04-17T12:33:13.000Z",
  "completed_at": "2026-04-17T12:33:13.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

1. Send a request to the API endpoint above
2. Save the request_id from the response
3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
4. When status is "COMPLETED", download from output.media_url

Tip: Use the X-Webhook-URL header to receive a callback instead of polling.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your request to receive a POST callback instead of polling.

X-Webhook-URL: https://your-server.com/webhook/callback

Request Parameters - Seedream 4 Multi-Image Edit

Content Item Types & Limits

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: $0.04"
}

Error via Status/Webhook

{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "byteplus",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "byteplus",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1776429228529-aq8fsc3s5k7-1.jpg"
    ],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-04-17T12:33:13.000Z",
  "updated_at": "2026-04-17T12:33:13.000Z",
  "completed_at": "2026-04-17T12:33:13.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

1. Send a request to the API endpoint above
2. Save the request_id from the response
3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
4. When status is "COMPLETED", download from output.media_url

Tip: Use the X-Webhook-URL header to receive a callback instead of polling.