Doubao Seedream 5.5 API
ByteDance Doubao Seedream 5.5 image API: pixel-level edits that hold across many rounds, native RGBA transparent output, and layer splitting into a base plus up to 100 transparent layers. One async endpoint covers text-to-image, editing from 1–10 reference images and layer splitting; one image per request at 1K, 1.5K or 2K, no watermark.
Authentication
All requests carry the API key in the header:
Authorization: Bearer YOUR_API_KEYPricing
| Field | Required | Type | Description |
|---|---|---|---|
| Item | Price | ||
| Per output image · 1K / 1.5K | $0.03 | ||
| Per output image · 2K | $0.05 | ||
| Per input image (reference / image to split) | +$0.01 |
A custom size is priced by pixel count: up to 2,601,123 pixels is $0.03, above that $0.05. Layer splitting reserves credit for max_images outputs, then settles on the layers actually returned and releases the rest. Charged only on success; failed requests are free.
Text-to-image
/v1/images/generationsAsync: create returns a taskId; poll GET ?task_id= until completed, or receive a webhook via callback_url. A 1K text-to-image request took about 20 seconds in our test.
# Text-to-image — create returns a taskId, then poll for the result.
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-5",
"prompt": "product photo of a matte white ceramic mug on a light oak table by a window, soft morning light",
"resolution": "1.5K",
"aspect_ratio": "16:9"
}'
# → { "code": 200, "data": { "taskId": "...", "state": "pending", "model": "doubao-seedream-5-5" } }
curl "https://api.apimodels.app/v1/images/generations?task_id=TASK_ID" \
-H "Authorization: Bearer YOUR_API_KEY"
# → { "code": 200, "data": { "state": "completed", "resultUrls": ["https://r2.apimodels.app/..."] } }Editing · multi-image composition · transparent background
Include image (one) or images (up to 10) to edit or compose; refer to them as image 1, image 2 in the prompt. background: "transparent" generates a PNG with a real alpha channel.
# Edit / compose — 1 to 10 reference images (+$0.01 each).
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-5",
"prompt": "put the vase from image 2 on the table in image 1; keep the room, furniture and lighting unchanged",
"images": ["https://example.com/dining-room.jpg", "https://example.com/vase.png"],
"resolution": "2K"
}'
# Transparent background — PNG with a real alpha channel.
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-5",
"prompt": "a snowy owl with spread wings, isolated, detailed feathers",
"background": "transparent",
"resolution": "1K"
}'Layer splitting
layer_decomposition: true with exactly one image returns a base image plus transparent PNG layers. resultUrls[i] pairs with layers[i], which carries the stacking order (z_index), the bounding_box and the role, plus the recognised text when text_recognition is on. A prompt is optional and describes how to split.
# Layer splitting — exactly one image in, a base plus transparent layers out.
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-5",
"image": "https://example.com/poster.png",
"layer_decomposition": true,
"max_images": 10,
"text_recognition": true
}'
# Completed task:
# { "state": "completed",
# "resultUrls": ["https://r2.apimodels.app/...base.png", "https://r2.apimodels.app/...layer1.png", ...],
# "layers": [
# { "index": 0, "role": "base", "size": "2048x2048", "z_index": 0, "background": "opaque" },
# { "index": 1, "role": "layer", "size": "800x160", "z_index": 1, "background": "transparent",
# "bounding_box": { "absolute": [120, 80, 920, 240] },
# "text_recognition": { "text": "Summer Sale", ... } } ] }Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| Field | Type | Description | |
| model | string | doubao-seedream-5-5 (alias: seedream-5.5) | |
| prompt | string | Required for text-to-image and editing; optional for layer splitting | |
| resolution | string | 1K / 1.5K / 2K (default 2K) | |
| aspect_ratio | string | auto / 1:1 / 4:3 / 3:4 / 16:9 / 9:16 / 3:2 / 2:3 / 21:9 / 9:21 / 1:2 / 2:1 / 1:3 / 3:1 / 4:5 / 5:4 | |
| size | string | Custom size such as 2816x1584; overrides resolution / aspect_ratio. Total pixels 921,600–4,624,220, width:height between 1:16 and 16:1 | |
| image / images / image_urls | string / string[] | 1–10 reference images (URL or data URI); exactly one for layer splitting | |
| background | string | auto (default) / transparent / opaque; transparent outputs PNG only | |
| output_format | string | jpeg (default) or png; in layer splitting it sets the base image only, layers are always PNG | |
| layer_decomposition | boolean | true = layer splitting | |
| max_images | integer | Layer splitting: maximum outputs including the base, 2–100, default 30 | |
| text_recognition | boolean | Layer splitting: recognise text on text layers (rich text), no extra fee | |
| callback_url | string | Webhook URL called when the task completes |
Limits
- One image per request and no 4K; n greater than 1 returns 400, so send separate requests for several images.
- Layer splitting takes exactly one image and cannot be combined with a transparent background or a custom size; max_images and text_recognition apply only to layer splitting and return 400 elsewhere.
- A transparent background with output_format: "jpeg" returns 400 (JPEG cannot carry transparency).
- Parameters that cannot be honoured return 400 with the reason instead of being silently ignored.
Not every request succeeds
Content review can refuse a prompt or an image; a request that keeps a real person's identity from a reference photo may be refused; and the upstream occasionally returns a temporary error. Failed requests are not charged and the reserved credit is released. The response carries the failure reason: for review refusals, change the prompt or image; for temporary errors, retry. Result files are deleted after 30 days, so download or re-host them promptly.
Try it in the Playground (text-to-image and editing; use the API for 1.5K, transparent backgrounds and layer splitting). For pointed edits marked with coordinates or hand-drawn marks, see Seedream 5.0 Pro.
FAQ
How do I split an image into layers with Seedream 5.5?
Send layer_decomposition: true with exactly one image to /v1/images/generations. max_images (2–100, default 30) caps the outputs including the base; text_recognition adds the recognised text. resultUrls[i] pairs with layers[i], which carries z_index, bounding_box and role.
How much does Seedream 5.5 cost?
$0.03 per output image at 1K or 1.5K, $0.05 at 2K, plus $0.01 per reference image. Layer splitting is charged for the layers actually returned. Failed requests are not charged.
Can Seedream 5.5 make transparent images?
Yes: pass background: "transparent" and the result is a PNG with a real alpha channel. JPEG cannot carry transparency, so transparent plus output_format jpeg returns 400.