ByteDance Seedream

Request basics

• Base URL: https://api.routeapi.ai
• Authentication: Authorization: Bearer $ROUTEAPI_KEY with an API Key starting with sk- (create one on the API Keys page). Management keys starting with rat_ cannot call models.
• Error format: {"error": {"message": "...", "type": "...", "code": "..."}}; see Common Errors for status code meanings.

Seedream models on sale: seedream-5.0-pro and seedream-5.0-lite. They are served by Volcengine (Doubao) channels and called through the same OpenAI-compatible images endpoints described on OpenAI Image Format; this page covers what the Volcengine adaptor changes.

Seedream models have image-generation in supported_endpoint_types — see Models for reading that field.

Endpoints

POST /v1/images/generations
POST /v1/images/edits

/v1/images/generations takes a JSON body. Image-to-image editing uses /v1/images/edits with the source image passed as a string in image; RouteAPI forwards both to the upstream image generation endpoint (Volcengine exposes no separate form-based edit endpoint through this channel).

Request parameters

Field	Type	Required	Description
model	string	Yes	seedream-5.0-pro or seedream-5.0-lite
prompt	string	Yes	Text description or edit instruction
size	string	No	Output size or tier. Normalized before it reaches Volcengine (see Size normalization)
image	string	No	Source image for image-to-image, as an http(s) URL or a data:image/...;base64,... string. Send it in a JSON body
watermark	boolean	No	Whether to watermark the output; an explicit false is forwarded
sequential_image_generation	string	No	"auto" enables multi-image generation; "disabled" turns it off
sequential_image_generation_options	object	No	Options for sequential generation; {"max_images": <int>} sets the count
layer_decomposition	boolean	No	Split the result into layers. When enabled it also changes how the request is priced (see Billing)
background	string	No	Background handling, for example "transparent" or "opaque"
tools	array	No	Upstream tools such as [{"type": "web_search"}]
optimize_prompt_options	object	No	Prompt optimization, for example {"mode": "standard"} or {"mode": "fast"}

These fields are part of the gateway’s image request struct and are forwarded to Volcengine. Optional fields you leave out are omitted from the upstream body rather than sent as null. Other unknown JSON fields are dropped — use request-body passthrough on the channel if you need a field the gateway does not model.

Size normalization

How size is treated depends on the model:

Model	size handling
seedream-5.0-pro	Native sizes are kept as sent: 1K, 1.5K, pixel strings such as 1024x1024, and other values
seedream-5.0-lite	Algebraic sizes are rewritten to a 2K / 3K / 4K tier

For models that are rewritten, the long side decides the tier: it is divided by 1024 and rounded to the nearest integer (ties round up), then clamped to the 2K–4K range. Tiers sent directly, such as 2K or 3k, are only clamped, and unrecognized values such as auto are passed through for Volcengine to validate. Examples for seedream-5.0-lite:

Requested size	Sent upstream
1024x1024	2K
2048x2048	2K
1536x1536	2K
1440x2560	3K
3840x2160	4K
1K	2K
5K	4K
auto	auto

Note

Because the size is rewritten, the image you receive for a rewritten model may not match the exact dimensions you asked for — it lands in the tier, with the aspect ratio chosen by the upstream. Request seedream-5.0-pro when you need an exact native size.

Generate an image

curl https://api.routeapi.ai/v1/images/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "A misty mountain lake at sunrise, cinematic",
    "size": "2K"
  }'

Sequential generation

curl https://api.routeapi.ai/v1/images/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite",
    "prompt": "A series of four postcards from the same coastal town, consistent style",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": { "max_images": 4 }
  }'

When sequential_image_generation is "auto" and no max_images is given, cost pre-estimation plans for 15 images if the model has extra-output pricing configured.

Edit an image

Send the source image as a string in the JSON body. The gateway forwards the image value to Volcengine unchanged — an http(s) URL or a data:image/...;base64,... string. The size normalization above still applies to the edit request.

curl https://api.routeapi.ai/v1/images/edits \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "Replace the background with a sunset beach, keep the subject unchanged",
    "image": "https://example.com/photo.png",
    "size": "2K"
  }'

layer_decomposition: true asks the upstream to split the result into separate layers; background: "transparent" asks for a transparent background. Both are forwarded unchanged.

Caution

Send edits as a JSON body. The gateway only reads the image field’s text value on this path — a file uploaded as multipart/form-data is not forwarded, and the request would reach Volcengine as a plain text-to-image call.

Response

The upstream images object is passed through to you. The fields you can parse are:

{
  "data": [
    {
      "url": "https://example.com/generated.png",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "input_images": 1,
    "generated_images": 1,
    "output_tokens": 4096,
    "total_tokens": 4096
  }
}

• Read images from data[].url. Each entry may report the delivered size, which can differ from the tier you requested.
• usage.input_images and usage.generated_images are used for settlement when the model is priced per image; output_tokens feeds token-based settlement.

Billing

Seedream models are priced per image when the model is configured that way. If the model detail page shows size tiers, the tier is chosen from the pixel count of the size you send, before a channel is selected. See Model Pricing and the model detail page for the price that applies.

Two Seedream-specific points:

• The adaptor rewrites size for seedream-5.0-lite, so the delivered image can land in a different tier than the one billed. To protect against that mismatch, size-tier-priced models are rejected with 400 when they route to a Volcengine channel — passthrough-body mode is exempt because the adaptor does not rewrite the body then.
• layer_decomposition: true switches the request to the layer-decomposition price configuration, where the model has one. Reference images beyond the free allowance and sequential outputs are also billed; the model detail page lists the numbers that apply.

Errors and limits

Status	Meaning	Typical cause
400	Invalid request	model missing, n above 128, × used as the size separator in a JSON body, or a size-tier-priced model routed to Volcengine
401	Authentication failed	Missing, invalid, expired, or exhausted API Key
403	Balance or quota exhausted	insufficient_user_quota or pre_consume_token_quota_failed
429	Rate limited	Reduce concurrency
500	Conversion or internal error	The request could not be converted, or the upstream returned no image

Upstream errors such as an unsupported size or a rejected prompt come back with the upstream’s status and message, with the RouteAPI request ID appended.

Next steps

• OpenAI Image Format — the shared /v1/images envelope and OpenAI models.
• Nano Banana — Gemini image models.
• Models — find image models and confirm image-generation support.
• Model Pricing — size tiers and per-image billing.