Doubao Seedream API
ByteDance's Doubao Seedream series. Multiple model tiers with text-to-image, image editing, and multi-image fusion capabilities.
Authentication
Authorization: Bearer YOUR_API_KEYModels & pricing
| Model | model | Price | Notes |
|---|---|---|---|
| Seedream 5.0 Pro | doubao-seedream-5-0-pro | $0.03 / $0.06 | Flagship, 1K/2K (tiered) |
| Seedream 5.0 Flash | doubao-seedream-5-0-flash | $0.03/image | Fast tier, 1K/2K same price, transparent-background edits and layer splitting (billed per output image) |
| Seedream 5.0 Lite (Official) | doubao-seedream-5-0-260128 | $0.055/image | Volcano Ark official, 2K/4K |
| Seedream 4.5 | doubao-seedream-4-5-251128 | $0.05/image | 2K/4K |
Code examples
# 5.0 Lite official channel: same endpoint for T2I and I2I.
# Provide image_url for image-to-image; omit it for text-to-image.
# size: "2K" (default) or "4K". aspect_ratio sets the shape (square when omitted).
# Step 1a: Text-to-image
curl -X POST https://api.apimodels.app/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedream-5-0-260128",
"prompt": "A cherry blossom tree by a tranquil river, impressionist painting style",
"size": "2K"
}'
# Step 1b: Image-to-image (same endpoint, just add image_url)
curl -X POST https://api.apimodels.app/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedream-5-0-260128",
"prompt": "Change the season to winter with snow",
"image_url": "https://example.com/landscape.jpg",
"size": "4K"
}'
# Step 2: Poll status
curl "https://api.apimodels.app/v1/images/generations?task_id=TASK_ID" \
-H "Authorization: Bearer YOUR_API_KEY"Layer decomposition (5.0 Flash only)
Same endpoint: add layer_decomposition: true and one PNG/JPEG, and you get one base image plus up to 16 transparent PNG layers, each with name, description, z_index and bounding_box, billed $0.03 per output image (17 reserved at create time, settled at the real count). Omit prompt to split every main element; name the parts ("Separate only the text.", "Separate the sneaker and the price tag.") to split only those.
# Layer decomposition (Seedream 5.0 Flash only): one PNG/JPEG in,
# a base image + up to 16 transparent PNG layers out, $0.03 per output image.
# Omit "prompt" to split every main element; name the parts ("Separate only the text.")
# for a selective split. The last sentence sets the language of layer names (default: Chinese).
curl -X POST https://api.apimodels.app/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedream-5-0-flash",
"image_url": "https://example.com/poster.jpg",
"layer_decomposition": true,
"prompt": "Separate every main element onto its own layer. Write every layer name and description in English.",
"size": "2K"
}'
# Poll. resultUrls = base first, then layers in z_index order;
# resultJson.layers[i] = { z_index, name, description, bounding_box: { absolute, normalized }, url }
curl "https://api.apimodels.app/v1/images/generations?task_id=TASK_ID" \
-H "Authorization: Bearer YOUR_API_KEY"Eight real cases (posters, product ad, icon, selective cutouts) with a layer-by-layer explorer: Seedream 5.0 Flash
Request parameters
| Field | Required | Type | Description |
|---|---|---|---|
| model | Yes | string | doubao-seedream-5-0-pro / doubao-seedream-5-0-flash / doubao-seedream-5-0-260128 / doubao-seedream-4-5-251128 |
| prompt | Yes | string | Text description or editing instructions; optional in layer-decomposition mode (omit it to split every main element) |
| image_url | No | string | Reference image: a public URL OR a base64/data-URI string. For 5.0 Lite: include for I2I, omit for T2I (same endpoint). |
| image_urls | No | string[] | Multiple reference images (4.5 only): each item may be a URL or a base64/data-URI string. |
| image_base64 | No | string | Base64/data-URI for a single local reference image (equivalent to passing base64 in image_url). |
| aspect_ratio | No | string | "1:1", "4:3", "3:4", "16:9", "9:16", "3:2", "2:3", "5:4", "4:5", "21:9" (all models; square when omitted). If both are given, aspect_ratio wins and size only selects the tier. |
| size | No | string | 5.0 Pro: 1K or 2K (default 2K, tiered $0.03 / $0.06, no 4K); 5.0 Flash: 1K or 2K (default 2K, both $0.03, no 4K); 5.0 Lite: 2K (default) or 4K |
| layer_decomposition | No | boolean | 5.0 Flash only: true splits one image into a base image plus up to 16 transparent PNG layers. Requires exactly one PNG or JPEG reference image; prompt is optional (omit it to split out every main element); size only reads the 1K / 2K tier and the base keeps the original aspect ratio; cannot be combined with background "transparent". Billed per output image at $0.03 (the base counts as one): the create call reserves the 17-image maximum and settles on the actual count. Result: resultUrls lists the base then each layer; resultJson.layers[i] gives z_index (0 is the base, higher is on top), name, description, bounding_box (absolute in pixels, normalized on 0–1000) and the matching url. Layer names and descriptions are written by the model and default to Chinese; append "Write every layer name and description in English." to the prompt to get English. Two measured facts: the base is not the original but the picture with the layers lifted off and filled in, and every layer PNG is larger than its bounding_box (about 2–4× per side, aspect preserved) — scale it to absolute when compositing. Measured 25–74 s. The model page shows eight real cases with a layer-by-layer explorer. |
| background | No | string | 5.0 Pro / Flash only: "transparent" edits one PNG that already has an alpha channel and keeps the transparency; output is PNG. Requires exactly one reference image; cannot create a transparent image from text alone; cannot be combined with output_format "jpeg". |
| resolution | No | string | 4.5 only: 1k / 2k / 3k / 4k |
| callback_url | No | string | Webhook URL called when task completes |
Notes
- Seedream 5.0 supports up to 3K resolution
- Seedream 4.5 and 4.0 support up to 4K resolution
- Multi-image fusion via image_urls array
- ⚠ Reference-image URLs must be publicly reachable AND fast — the upstream (Volcengine, in China) downloads the URL itself, and slow/overseas hosts (e.g. Railway free tier) often fail with a cross-border download timeout. For reliability, pass base64 / data-URI, or use a fast CDN.
Related: for the detailed 5.0 Pro docs see Seedream 5.0 Pro; model pages: Seedream 5.0 Lite · Seedream 5.0 Pro · Seedream 5.0 Flash (each has a Playground to try it)
FAQ
Which Seedream model should I pick?
5.0 Pro is the flagship (1K/2K, interactive editing); 5.0 Lite is the official channel at $0.055 with 2K/4K; 4.5 is the budget tier at $0.05 with up to 4K and multi-image fusion via image_urls[].
Why does my reference-image request fail with a download timeout?
The upstream (in China) downloads your URL itself; slow or overseas hosts often time out cross-border. Pass base64 / data-URI instead, or host the image on a fast CDN.