Seedream API: generate and edit from $0.018

Seedream is the BytePlus ModelArk image model family; 5.0 Flash and 5.0 Pro are the newest versions. On LaoZhang API, generation and edits share one JSON endpoint, billed per output image.

Version	Model ID	Price per image	Notes
Seedream 5.0 Flash	`seedream-5-0-flash-260915`	$0.018	Fast, lowest price; supports layers
Seedream 5.0 Pro	`seedream-5-0-pro-260628`	$0.12	Highest quality, about 2 minutes; supports layers
Seedream 5.0	`seedream-5-0-260128`	$0.035	Used in the examples
Seedream 4.5	`seedream-4-5-251128`	$0.045	—
Seedream 4.0	`seedream-4-0-250828`	$0.035	—

Public prices as of September 25, 2026 (model and pricing catalog). Reference images are free, except on 5.0 Pro: $0.003 each after the first. Layer decomposition is also billed per output image.

A realistic sunset over mountains, generated by Seedream 5.0 — Output of the generate example below: Seedream 5.0, 2K

Item	Details
Endpoint	`POST /v1/images/generations`, JSON body
Generate or edit	Send only `prompt` to generate; add `image` to edit
Reference images	`image` takes one image, or an array of up to 10
Key	`default` group, billing mode Usage first (recommended) or Per-call
Concurrency	No platform cap or throttling; a `429` means upstream capacity (Concurrency and 429)

To call another version, change model. 5.0 Flash and 5.0 Pro return HTTP 400 for sequential_image_generation or stream, so remove both first, including the edit examples’ "sequential_image_generation": "disabled" line.

Before you start

Create a key for per-call models

Seedream is a per-call (按次) model. In Token management, create a key (or edit an existing one) and set Billing mode (计费模式) to Usage first (按量优先, recommended) or Per-call (按次计费). A Usage first key can also call usage-based models; a Per-call key can only call per-call models.Keep the key in a server-side environment variable.

In Token management, create a token with Billing mode set to Per-call (按次计费), then select Create.

Set up your environment

Export the key and install requests, which the Python examples use:

export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"
python3 -m pip install requests

Generate an image

This request creates a 2K image without a watermark and writes the response to seedream-generation.json:

curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-260128",
    "prompt": "A beautiful sunset over mountains, realistic style",
    "size": "2K",
    "response_format": "url",
    "watermark": false
  }' \
  -o seedream-generation.json

A successful response lists the image in data:

{
  "created": 1726051200,
  "data": [
    {
      "url": "https://example.com/generated_image.jpg"
    }
  ]
}

Save the result

Download the image as soon as the response arrives. Save this script as save_images.py; it saves every image in a response, whether it arrives as url or b64_json:

save_images.py

import base64
import json
import sys
import urllib.request
from pathlib import Path

response_file, stem = sys.argv[1], sys.argv[2]
response = json.loads(Path(response_file).read_text())
if not response.get("data"):
    sys.exit(f"No image in {response_file}: {response}")

for number, item in enumerate(response["data"], start=1):
    if item.get("b64_json"):
        # Drop an optional data:image/...;base64, prefix and restore missing padding.
        value = item["b64_json"].split(",", 1)[-1]
        image = base64.b64decode(value + "=" * (-len(value) % 4))
    else:
        with urllib.request.urlopen(item["url"], timeout=120) as download:
            image = download.read()
    if image.startswith(b"\x89PNG"):
        extension = "png"
    elif image[:4] == b"RIFF" and image[8:12] == b"WEBP":
        extension = "webp"
    else:
        extension = "jpg"
    path = Path(f"{stem}-{number}.{extension}")
    path.write_bytes(image)
    print(f"Saved {path}")

python3 save_images.py seedream-generation.json seedream-sunset

The script prints a line such as Saved seedream-sunset-1.jpg. Open the file and check the result.

Generate with Python

import base64
import os
from pathlib import Path

import requests

response = requests.post(
    "https://api.laozhang.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"},
    json={
        "model": "seedream-5-0-260128",
        "prompt": "A beautiful sunset over mountains, realistic style",
        "size": "2K",
        "response_format": "url",
        "watermark": False,
    },
    timeout=180,
)
response.raise_for_status()
item = response.json()["data"][0]

if item.get("b64_json"):
    value = item["b64_json"].split(",", 1)[-1]
    image = base64.b64decode(value + "=" * (-len(value) % 4))
else:
    download = requests.get(item["url"], timeout=120)
    download.raise_for_status()
    image = download.content

extension = "png" if image.startswith(b"\x89PNG") else "jpg"
output = Path(f"seedream-sunset.{extension}")
output.write_bytes(image)
print(f"Saved {output}")

Edit an image

Add image to the request to edit or redraw an existing image. This example uses a public sample image from the BytePlus documentation, so you can run it as is:

curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-260128",
    "prompt": "Generate a close-up image of a dog lying on lush grass.",
    "image": "https://ark-doc.tos-ap-southeast-1.bytepluses.com/doc_image/seedream4_imageToimage.png",
    "sequential_image_generation": "disabled",
    "size": "2K",
    "response_format": "url",
    "watermark": false
  }' \
  -o seedream-edit.json

python3 save_images.py seedream-edit.json seedream-edit

Combine up to 10 reference images

Pass image as an array to use several references. Each item is a public URL or a data URL such as data:image/png;base64,..., and the images are numbered in array order, so the prompt can refer to image 1, image 2, and so on. This example sends three local files as data URLs:

IMG1=$(base64 < product.png | tr -d '\n')
IMG2=$(base64 < scene.jpg | tr -d '\n')
IMG3=$(base64 < style.jpg | tr -d '\n')

curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- \
  -o seedream-multi-edit.json <<EOF
{
  "model": "seedream-5-0-260128",
  "prompt": "Place the product from image 1 in the scene from image 2, and apply the lighting and color style of image 3. Keep the product shape, label, and colors.",
  "image": [
    "data:image/png;base64,$IMG1",
    "data:image/jpeg;base64,$IMG2",
    "data:image/jpeg;base64,$IMG3"
  ],
  "sequential_image_generation": "disabled",
  "size": "2K",
  "response_format": "url",
  "watermark": false
}
EOF

python3 save_images.py seedream-multi-edit.json seedream-multi-edit

Combine references with Python

This function accepts one to ten references, converts local files to data URLs, and passes public URLs through unchanged:

import base64
import mimetypes
import os
from pathlib import Path

import requests

API_URL = "https://api.laozhang.ai/v1/images/generations"
HEADERS = {"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"}


def to_image_input(source):
    """Return a URL unchanged, or convert a local file to a data URL."""
    if source.startswith(("https://", "http://", "data:")):
        return source
    path = Path(source)
    mime_type = mimetypes.guess_type(path.name)[0] or "image/png"
    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
    return f"data:{mime_type};base64,{encoded}"


def seedream_edit(prompt, sources, model="seedream-5-0-260128"):
    if not 1 <= len(sources) <= 10:
        raise ValueError("Seedream accepts 1 to 10 reference images")
    images = [to_image_input(source) for source in sources]
    response = requests.post(
        API_URL,
        headers=HEADERS,
        json={
            "model": model,
            "prompt": prompt,
            "image": images[0] if len(images) == 1 else images,
            "sequential_image_generation": "disabled",
            "size": "2K",
            "response_format": "url",
            "watermark": False,
        },
        timeout=180,
    )
    response.raise_for_status()
    return response.json()


def save_all_images(result, stem):
    """Save every item in data[]; sequential generation can return several images."""
    paths = []
    for number, item in enumerate(result["data"], start=1):
        if item.get("b64_json"):
            value = item["b64_json"].split(",", 1)[-1]
            image = base64.b64decode(value + "=" * (-len(value) % 4))
        else:
            download = requests.get(item["url"], timeout=120)
            download.raise_for_status()
            image = download.content
        extension = "png" if image.startswith(b"\x89PNG") else "jpg"
        path = Path(f"{stem}-{number}.{extension}")
        path.write_bytes(image)
        paths.append(path)
    return paths


result = seedream_edit(
    "Place the product from image 1 in the scene from image 2, and apply the "
    "lighting and color style of image 3. Keep the product shape, label, and colors.",
    ["product.png", "scene.jpg", "style.jpg"],
)
for path in save_all_images(result, "seedream-python-edit"):
    print("Saved", path)

Split an image into transparent layers

Seedream 5.0 Flash (seedream-5-0-flash-260915) and 5.0 Pro (seedream-5-0-pro-260628) can decompose one finished image into a background plus separate transparent PNG layers, one element per layer. Use this to swap backgrounds, rearrange a layout, or reuse elements. Both models charge for every image they return, and each Pro image costs about 6.7 times as much as a Flash image, so start with Flash. Asking for a transparent background in a normal prompt doesn’t produce an alpha channel; layer decomposition does. A layer request differs from a normal edit in a few ways:

Set layer_decomposition to true.
Send exactly one image in image, either as a string or as a one-item array.
prompt is optional. Leave it out or send an empty string, and the model detects the main elements on its own.
Set size to 1K. Exact pixels aren’t accepted.
Layer requests accept only the levels 1K, 1.5K, 2K, and auto.
Only 5.0 Flash and 5.0 Pro support it. On seedream-5-0-260128 and seedream-4-5-251128, the parameter returns HTTP 400 with the error code InvalidParameter.

Send a layer request

curl --fail-with-body --max-time 360 "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-flash-260915",
    "image": "https://example.com/your-poster.jpg",
    "layer_decomposition": true,
    "size": "1K",
    "response_format": "url",
    "watermark": false
  }' \
  -o seedream-layers.json

Replace the image URL with a publicly downloadable image of your own, or pass a data URL. To use 5.0 Pro, change only model.

Layer decomposition charges for every returned image: $0.018 each on Flash and $0.12 each on Pro.

The model decides how many layers to return, and the count can differ between runs of the same image. A movie poster that splits into 6 images (1 background and 5 layers) costs $0.108 on Flash and $0.72 on Pro. Busier images can return a dozen or more, and 16 images on Flash cost $0.288.
At 1K, a 6-image result takes under a minute on Flash and about 70 seconds on Pro, and more layers take longer. Set the client timeout to at least 300 seconds. A 2K request can run for a long time and is still charged if your client disconnects.
If an image can’t be decomposed, the request returns HTTP 400 and isn’t charged. You can retry it.
The model paints in the areas behind removed elements, so check the background before commercial use.

Read the layer response

The first item in data[] is the background, and each remaining item is one layer. This response is trimmed to the background and a single layer:

{
  "data": [
    {
      "url": "https://example.com/base.jpeg",
      "size": "896x1200",
      "output_format": "jpeg",
      "z_index": 0
    },
    {
      "url": "https://example.com/layer.png",
      "size": "916x529",
      "output_format": "png",
      "z_index": 4,
      "bounding_box": {
        "absolute": [260, 716, 619, 924],
        "normalized": [290, 597, 690, 769]
      },
      "name": "Spaceship",
      "description": "Sci-fi spaceship with blue engine glow effects, separate from the background nebula."
    }
  ],
  "usage": {
    "input_images": 1,
    "generated_images": 6
  }
}

Field	Meaning
`url`	Temporary download link; save the file promptly. The link sends no CORS headers, so browser clients should request `"response_format": "b64_json"` and read each image from the `b64_json` field instead
`size`	Pixel dimensions of this image file
`output_format`	The background follows the request’s `output_format` (`jpeg` by default); layers are always RGBA `png`
`z_index`	Stacking order: 0 for the background, then 1 and up for layers, with higher values on top
`bounding_box.absolute`	Layer position on the background as `[left, top, right, bottom]` in background pixels
`bounding_box.normalized`	The same box on a 0–1000 scale
`name`, `description`	English label and description the model writes for each layer; the background has neither
`usage.generated_images`	Number of returned images, including the background

usage also includes output_tokens, but the charge depends only on the image count. A layer file isn’t necessarily the size of its bounding box. In the example, a 916×529 PNG belongs in a 359×208 box, so scale each layer to its absolute box when you put the image back together.

Save the layers and recompose the image

This script reads seedream-layers.json, saves every image with its z_index and name in the filename, and uses Pillow to paste each layer into its bounding_box.absolute box on the background. Install Pillow first with python3 -m pip install pillow.

save_layers.py

import json
import re
import sys
import urllib.request
from io import BytesIO
from pathlib import Path

from PIL import Image

response = json.loads(Path(sys.argv[1]).read_text())
canvas = None

# Lowest z_index first: the background, then each layer on top.
for item in sorted(response["data"], key=lambda item: item["z_index"]):
    with urllib.request.urlopen(item["url"], timeout=120) as download:
        content = download.read()
    name = re.sub(r"[^a-z0-9]+", "-", item.get("name", "base").lower()).strip("-")
    extension = "png" if item["output_format"] == "png" else "jpg"
    path = Path(f"layer-{item['z_index']:02d}-{name or 'layer'}.{extension}")
    path.write_bytes(content)
    print(f"Saved {path}")

    image = Image.open(BytesIO(content)).convert("RGBA")
    if "bounding_box" not in item:
        canvas = image  # The background has no bounding_box.
        continue
    left, top, right, bottom = item["bounding_box"]["absolute"]
    layer = image.resize((right - left, bottom - top), Image.LANCZOS)
    canvas.alpha_composite(layer, (left, top))

canvas.save("recomposited.png")
print("Saved recomposited.png")

python3 save_layers.py seedream-layers.json

You get files such as layer-00-base.jpg and layer-04-spaceship.png, plus recomposited.png. To change the background or drop an element, swap the background file or skip that layer before you composite.

Parameters

Parameter	Type	Required	Description
`model`	string	Yes	A model ID from the table at the top of this page, such as `seedream-5-0-flash-260915` or `seedream-5-0-260128`
`prompt`	string	Yes	Image description or editing instruction. Optional for layer decomposition
`image`	string or array	For edits	One reference as a string, or up to 10 as an array; each is a public URL or data URL. Exactly one for layer decomposition
`size`	string	No	Output size; the examples use `2K`. Levels differ by model; see the FAQ
`response_format`	string	No	`url` (default) or `b64_json`
`output_format`	string	No	`png` or `jpeg` on 5.0 Flash, 5.0 Pro, and 5.0. With layer decomposition, it sets the background format only
`watermark`	boolean	No	Set `false` to omit the watermark
`sequential_image_generation`	string	No	`disabled` (default) returns one image, as in the examples; `auto` turns on sequential generation, where the model decides how many images to return (see the FAQ). Not supported by 5.0 Flash or 5.0 Pro
`layer_decomposition`	boolean	No	5.0 Flash and 5.0 Pro. `true` splits one reference image into a background and transparent layers; see Split an image into transparent layers

5.0 Flash and 5.0 Pro return HTTP 400 if the request includes sequential_image_generation (even "disabled") or stream. They also ignore n, so each request returns one image unless you use layer decomposition. Sequential generation and layer decomposition can return several images in one response, so save every item in data[], as save_images.py, save_all_images, and save_layers.py do.

Frequently asked questions

Which Seedream version should I use?

Choose by what the task needs:

Low price, speed, or high volume: Seedream 5.0 Flash (seedream-5-0-flash-260915), at $0.018 per image. BytePlus positions it for ad creatives, product images, and posters or other designs with text.
Highest quality: Seedream 5.0 Pro (seedream-5-0-pro-260628), for realistic portraits, fine material detail, and complex instructions. At $0.12 per image it costs about 3.4 times as much as 5.0 and is slower, so use 5.0 or Flash for routine work.
3K output, sequential generation, or streaming: Seedream 5.0 (seedream-5-0-260128). The BytePlus documentation calls this model Seedream 5.0 lite; it supports 2K and 3K output, up to 3K.
4K: Seedream 4.5 (seedream-4-5-251128) or 4.0 (seedream-4-0-250828). Otherwise, keep these two versions only when an existing workflow depends on their output.
Transparent layers from an existing image: layer decomposition on 5.0 Flash. 5.0 Pro supports it too, at about 6.7 times the price per image.

The model and pricing catalog lists current prices for every version.

How is Seedream API pricing calculated?

You pay a fixed price for each returned image, set by the model version: from $0.018 on 5.0 Flash to $0.12 on 5.0 Pro, as listed in the price table at the top of this page.

Output size doesn’t change the price.
A request that returns several images, such as sequential generation, is billed per image.
Reference images are free, except on 5.0 Pro, where each one after the first costs $0.003.
Non-200 responses aren’t charged.

Does the Seedream API have rate limits or a concurrency cap?

No. LaoZhang API sets no concurrency cap or throttling on Seedream. An occasional 429 comes from upstream capacity, isn’t charged, and can be retried after a short wait; see Concurrency and 429.

What values does `size` accept? Can I get 4K?

Use one of two forms, not both. Either pass a resolution level and describe the aspect ratio in the prompt (for example, “a 16:9 landscape”), or pass exact pixels such as 2848x1600. Each model supports these resolution levels:

seedream-5-0-flash-260915: 1K, 1.5K, 2K (defaults to 2K)
seedream-5-0-pro-260628: 1K, 2K
seedream-5-0-260128: 2K, 3K (up to 3K)
seedream-4-5-251128: 2K, 4K
seedream-4-0-250828: 1K, 2K, 4K

Exact pixels must meet both a total-pixel range and an aspect-ratio range:

Minimum: 2560×1440 (3,686,400 pixels) for 5.0 and 4.5, and 1280×720 (921,600 pixels) for 4.0.
Maximum: 4096×4096 for 4.5 and 4.0, and the 3K level for 5.0.
5.0 Flash: 921,600 to 4,624,220 pixels in total.
5.0 Pro: up to about 4.19 million pixels, such as 2048x2048, or 2720x1530 for 16:9.
Aspect ratio: from 1/16 to 16 on 5.0 Flash, 5.0, 4.5, and 4.0.

That’s why a small size such as 1024x1024 fails on 5.0 and 4.5. With a resolution level, 5.0 Flash chooses the aspect ratio from the content, so pass exact pixels such as 2560x1440 when you need a fixed ratio. On 5.0 Flash, 3K and 4K return HTTP 400. The per-image price doesn’t change with size. Layer decomposition accepts only 1K, 1.5K, 2K, or auto, not exact pixels.

How does sequential generation work, and how is it billed?

Set sequential_image_generation to auto, and the model decides from the prompt how many related images to return, for example “three images of the same character in the morning, at noon, and at night.” To cap the count, BytePlus documents sequential_image_generation_options.max_images (1–15). Reference images plus generated images can’t exceed 15. The response then lists several images in data[], so save every item. You pay for each returned image, so four images from seedream-5-0-260128 cost $0.14; reference images aren’t charged. Check call logs for the actual charge. 5.0 Flash and 5.0 Pro don’t support sequential generation: any sequential_image_generation value, including "disabled", returns HTTP 400. Use 5.0 for sequential generation, or send one request per image to Flash or Pro.

How do I send a local image, and what are the limits?

Convert it to a data URL in the form data:image/png;base64,<Base64 data>, with the format name in lowercase, such as png or jpeg. The Python helper does this for you. BytePlus sets these limits for each reference:

Format: jpeg, png, webp, bmp, tiff, gif, heic, or heif.
Size: up to 30 MB.
Dimensions: width and height each more than 14 pixels, and no more than 6000×6000 pixels in total.
Aspect ratio: between 1/16 and 16.

A public URL must be directly downloadable. For large images, prefer a public URL: Base64 encoding makes the request body about a third larger.

How do I remove the watermark?

Send "watermark": false, as every example on this page does. BytePlus defaults watermark to true, which adds an “AI generated” label to the lower-right corner, so set it to false explicitly when you need a clean image.

How long do result URLs last? Can I get Base64 instead?

BytePlus says image URLs stay valid for 24 hours after generation. Download the image as soon as the response arrives and keep your own copy; don’t store the returned URL as a permanent address. To receive the image inside the response, set response_format to b64_json. The save_images.py script and the Python examples handle both formats.

Am I charged for failed requests?

No. A non-200 response, such as a parameter error or a moderation block, isn’t charged; you pay only when images are returned. A client timeout isn’t the same as a failure. The server may have finished and charged for the image, so check call logs before you resend. Call logs are the final record of what you were charged. Set the client timeout by model to avoid cutting off requests that are still running:

5.0 Flash: at least 60 seconds. BytePlus says it finishes within 20 seconds; with ten references, expect about 30 seconds.
5.0 Pro: at least 240 seconds, because a request typically takes about 2 minutes.
Layer decomposition on 5.0 Flash or 5.0 Pro: at least 300 seconds at 1K.

Seedream 5.0 Flash and 5.0 Pro launch: prices, migration notes, and version comparison
Choose an image generation API: compare Seedream with other image models
Images API reference: shared request and response format
Model and pricing catalog: current Seedream prices and groups
Call logs: check the model and charge for each request

Sources

BytePlus ModelArk image generation API: official Seedream request parameters, size ranges, and URL lifetime
BytePlus image generation tutorial: model comparison, sequential generation, and input image limits
Seedream 4.0 user manual: prompting guidance and examples from BytePlus
Models and pricing in the console: prices available to your account

Get started

Image Generation & Editing APIs

Video Generation APIs

Text APIs

Multimodal & Audio APIs

Seedream API: generate and edit from $0.018

Before you start

Generate an image

Save the result

Generate with Python

Edit an image

Combine up to 10 reference images

Combine references with Python

Split an image into transparent layers

Send a layer request

Read the layer response

Save the layers and recompose the image

Parameters

Frequently asked questions

Which Seedream version should I use?

How is Seedream API pricing calculated?

Does the Seedream API have rate limits or a concurrency cap?

What values does `size` accept? Can I get 4K?

How does sequential generation work, and how is it billed?

How do I send a local image, and what are the limits?

How do I remove the watermark?

How long do result URLs last? Can I get Base64 instead?

Am I charged for failed requests?

Sources

​Before you start

​Generate an image

​Save the result

​Generate with Python

​Edit an image

​Combine up to 10 reference images

​Combine references with Python

​Split an image into transparent layers

​Send a layer request

​Read the layer response

​Save the layers and recompose the image

​Parameters

​Frequently asked questions

​Which Seedream version should I use?

​How is Seedream API pricing calculated?

​Does the Seedream API have rate limits or a concurrency cap?

​What values does size accept? Can I get 4K?

​How does sequential generation work, and how is it billed?

​How do I send a local image, and what are the limits?

​How do I remove the watermark?

​How long do result URLs last? Can I get Base64 instead?

​Am I charged for failed requests?

​Related documentation

​Sources

Before you start

Generate an image

Save the result

Generate with Python

Edit an image

Combine up to 10 reference images

Combine references with Python

Split an image into transparent layers

Send a layer request

Read the layer response

Save the layers and recompose the image

Parameters

Frequently asked questions

Which Seedream version should I use?

How is Seedream API pricing calculated?

Does the Seedream API have rate limits or a concurrency cap?

What values does `size` accept? Can I get 4K?

How does sequential generation work, and how is it billed?

How do I send a local image, and what are the limits?

How do I remove the watermark?

How long do result URLs last? Can I get Base64 instead?

Am I charged for failed requests?

Related documentation

Sources