# Seedream 5.5 Seedream 5.5 is ByteDance's image model. One request makes one image from a prompt, from a prompt plus up to 10 reference images, or splits one image into a base image and transparent layers, optionally with the text of each text layer read back. Send the request, keep the returned task ID, and read the finished images from the task. Reference images go in as URLs. ## Model IDs | Model ID | Inputs | Output size | Images per request | | -------------- | ----------------- | ------------------------------------ | ---------------------------------------------------------- | | `seedream-5-5` | text, 0–10 images | `1K`, `1.5K`, `2K` or `WIDTHxHEIGHT` | 1, or 2–100 with layer decomposition (base image included) | See the [model page](https://seedrouter.ai/models/seedream-5-5#pricing) for current prices. ## Quick example ```bash curl https://api.seedrouter.ai/v1/images/generations \ -H "Authorization: Bearer $SEEDROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "seedream-5-5", "prompt": "A ceramic teapot shaped like a sleeping fox on a linen tablecloth, soft morning window light, shallow depth of field. No text.", "size": "1K" }' ``` ```python import os import requests response = requests.post( "https://api.seedrouter.ai/v1/images/generations", headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}, json={ "model": "seedream-5-5", "prompt": "A ceramic teapot shaped like a sleeping fox on a linen tablecloth, soft morning window light, shallow depth of field. No text.", "size": "1K", }, timeout=60, ) response.raise_for_status() task_id = response.json()["id"] ``` ```javascript const response = await fetch('https://api.seedrouter.ai/v1/images/generations', { method: 'POST', headers: { Authorization: `Bearer ${process.env.SEEDROUTER_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'seedream-5-5', prompt: 'A ceramic teapot shaped like a sleeping fox on a linen tablecloth, soft morning window light, shallow depth of field. No text.', size: '1K', }), }); if (!response.ok) throw new Error(`Request failed: ${response.status}`); const { id: taskId } = await response.json(); ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "strings" "time" ) func main() { body := strings.NewReader(`{ "model": "seedream-5-5", "prompt": "A ceramic teapot shaped like a sleeping fox on a linen tablecloth, soft morning window light, shallow depth of field. No text.", "size": "1K" }`) req, err := http.NewRequest("POST", "https://api.seedrouter.ai/v1/images/generations", body) if err != nil { panic(err) } req.Header.Set("Authorization", "Bearer " + os.Getenv("SEEDROUTER_API_KEY")) req.Header.Set("Content-Type", "application/json") client := &http.Client{Timeout: 60 * time.Second} res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { panic(res.Status) } var task struct { ID string `json:"id"` } if err := json.NewDecoder(res.Body).Decode(&task); err != nil { panic(err) } fmt.Println(task.ID) } ``` ## Endpoint ```text POST https://api.seedrouter.ai/v1/images/generations ``` | Header | Value | | ------------- | --------------------- | | Authorization | `Bearer YOUR_API_KEY` | | Content-Type | `application/json` | The response is a task (`{"id": "task_...", "status": "processing"}`), not the finished image. Poll `GET /v1/tasks/{task_id}` for the result. Keep API keys in server-side code. References and layer decomposition go in the same request through `image`; `/v1/images/edits` is not used for this model and returns 400. ## Parameters | Field | Type | Default | Notes | | ---------------------------------------------- | --------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model` | string | required | `seedream-5-5` | | `prompt` | string | required | Describes the image to make. Optional with `layer_decomposition`: say which elements to split out, or leave it out and the model finds the subjects, text and background itself. | | `image` | URL or URL list | none | One public image URL, or a list of up to 10. Without it the request is text to image. With `layer_decomposition`, exactly one. Every reference is billed. | | `size` | string | `2K` | A tier `1K`, `1.5K` or `2K`, or exact pixels `WIDTHxHEIGHT` — see [Output size](#output-size). With `layer_decomposition`: `auto` (default), `1K`, `1.5K` or `2K` only. | | `output_format` | enum | `png` | `png` or `jpeg`. With `layer_decomposition` it sets the base image only; layers are always PNG. | | `background` | enum | `auto` | `auto`, `opaque` or `transparent`. `transparent` works with or without references and requires `png` output. Leave it out with `layer_decomposition`, including `auto`. | | `layer_decomposition` | boolean | `false` | Split the one input image into a base image and transparent PNG layers. | | `layer_decomposition_options.max_images` | integer | `30` | Only with `layer_decomposition`. 2–100, the base image included. It is a cap: the model may return fewer. | | `layer_decomposition_options.text_recognition` | boolean | `false` | Only with `layer_decomposition`. Adds the recognized text to regular text layers — see [Text recognition](#text-recognition). | | `optimize_prompt_options.mode` | enum | `standard` | Only `standard`. Prompt optimization is always on and cannot be turned off. | | `watermark` | boolean | `false` | `true` adds an "AI generated" mark. | | `content_filter` | boolean | `true` | Available through the API only. The Playground always keeps it on. | Fields outside this list are dropped before the request is forwarded; they never cause an error and never change the output. `n`, `stream`, `seed` and `response_format` are not available: each request returns one image, or with `layer_decomposition` up to `max_images`. `callback_url` is not available; poll the task instead. ## Output size | Form | Example | Rules | | ------------ | --------------------- | ----------------------------------------------------------------------------------------------- | | Tier | `"size": "2K"` | `1K`, `1.5K` or `2K`. Describe the shape in `prompt`; the model picks the aspect ratio from it. | | Exact pixels | `"size": "2560x1440"` | Total pixels 921,600 to 4,624,220; width / height between 1/16 and 16. | There is no 3K or 4K tier and no ratio form: for a fixed 16:9 frame at 2K, send `2560x1440`. `1K` and `1.5K` cost the same; `2K` and any size above 2.61 million pixels cost more (see [Pricing dimensions](#pricing-dimensions)). ## Reference images Pass one image to edit it, or several to combine them, and say in `prompt` what to keep and what to change. Refer to them by order ("the jacket from image 1"). ```json { "model": "seedream-5-5", "prompt": "Turn this scene into a snowy winter night with warm light from the lighthouse windows, keep the composition", "image": "https://example.com/lighthouse.jpg", "size": "2560x1440" } ``` ## Transparent background Set `background: "transparent"` for a PNG whose background is transparent, from a prompt alone or from references: ```json { "model": "seedream-5-5", "prompt": "A glossy red enamel pin shaped like a cherry, product cutout", "background": "transparent", "output_format": "png", "size": "1K" } ``` ## Layer decomposition Send exactly one image with `layer_decomposition: true`. The task returns the base image first and then each layer as a transparent PNG. ```json { "model": "seedream-5-5", "image": "https://example.com/poster.jpg", "layer_decomposition": true, "size": "1K", "layer_decomposition_options": { "max_images": 4, "text_recognition": true } } ``` Each layer carries `z_index` (the base image is 0; higher numbers sit on top), `background`, and when the model provides them `name`, `description` and `bounding_box`. `bounding_box.absolute` is `[left, top, right, bottom]` in pixels of the base image; `bounding_box.normalized` is the same box scaled to 0–1000. Layer files are rendered at the chosen tier, so their pixel size can differ from the box: to rebuild the picture, scale each layer to its box and place it on the base image in ascending `z_index` order. A tier sets the size of the base image and every layer. With `auto`, the output follows the input image, raised to at least `1K` and lowered to at most `2K`. ### Text recognition With `layer_decomposition_options.text_recognition: true`, a layer that holds regular printed text also carries `text_recognition`: the full `text` (lines joined by `\n`), and `lines`, each with its own `bounding_box` and `runs` of differently styled text. A run's `style` has `similar_font_family`, `foreground_color` (`#RRGGBB`) and the marks `bold`, `italic`, `underline`, `strikethrough`, `shadow` and `translucent`. Fonts and marks are the model's estimate. Artistic or handwritten lettering returns no text, and a `prompt` sent with the split may suppress it, so treat the field as optional. ## Media inputs Each reference is a public HTTP(S) URL. Base64 data URIs are not accepted: upload the file to your own storage and pass its URL. Accepted formats are JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC and HEIF, up to 30 MB each and at most 36,000,000 pixels in total. AVIF and JP2 are not supported; a task that cannot read its input fails and is not charged. ## Pricing dimensions Check the [model pricing section](https://seedrouter.ai/models/seedream-5-5#pricing) for current rates. Seedream 5.5 is priced per output image by pixel tier, plus every reference image: ```text cost = Σ each returned image's price for its own tier + reference images × reference price ``` * The lower tier covers images up to 2.61 million pixels (`1K` and `1.5K`); anything larger is the upper tier. * Every reference image is billed, the first one included. Layer decomposition bills its one input image. * Layer decomposition charges the base image and every layer, each at the tier of its own size. * The amount reserved when a task is accepted covers the largest result: one image at the requested tier, or `max_images` images (30 when omitted) for layer decomposition, with `auto` counted as the upper tier. The task is then charged for the images actually returned, and the difference is released. View final charges in your account usage history. Failed tasks are not charged. ## Output schema Submission returns the task: ```json {"id": "task_...", "model": "seedream-5-5", "status": "processing", "created_at": 1794323757} ``` ### Get the task ```text GET https://api.seedrouter.ai/v1/tasks/{task_id} ``` Poll every 10–20 seconds until `status` is `completed` or `failed`. A network timeout while polling does not mean generation failed: keep the task ID and resume checking it. Do not create another task to check progress. ### Completed task ```json { "id": "task_...", "model": "seedream-5-5", "status": "completed", "created_at": 1794323757, "finished_at": 1794323804, "output": { "data": [ { "url": "https://static.seedrouter.ai/media/tasks/task_example/0.png", "size": "1248x832", "output_format": "png", "background": "opaque" } ] } } ``` A layer decomposition task lists the base image and then each layer. This is a real split of a poster with text recognition on; the base image and the first of its three layers are shown: ```json { "data": [ { "url": "https://static.seedrouter.ai/media/tasks/task_example/0.png", "size": "836x1254", "output_format": "png", "background": "opaque", "z_index": 0 }, { "url": "https://static.seedrouter.ai/media/tasks/task_example/1.png", "size": "1455x721", "output_format": "png", "background": "transparent", "z_index": 1, "name": "Dark blue serif main title text with dash decorations", "description": "Dark blue serif main title text reading \"BLUE TIDE SESSIONS\", with short horizontal dash decorations on its left and right sides.", "bounding_box": { "absolute": [0, 0, 836, 414], "normalized": [0, 0, 1000, 330] }, "text_recognition": { "text": "BLUE TIDE\nSESSIONS", "lines": [ { "bounding_box": { "absolute": [146, 69, 694, 196], "normalized": [175, 55, 830, 156] }, "runs": [ { "text": "BLUE TIDE", "style": { "similar_font_family": "HTF Didot", "foreground_color": "#122C4D", "bold": false, "italic": false, "underline": false, "strikethrough": false, "shadow": false, "translucent": false } } ] }, { "bounding_box": { "absolute": [175, 168, 664, 300], "normalized": [209, 134, 794, 239] }, "runs": [ { "text": "SESSIONS", "style": { "similar_font_family": "HTF Didot", "foreground_color": "#122C4D", "bold": false, "italic": false, "underline": false, "strikethrough": false, "shadow": false, "translucent": false } } ] } ] } } ] } ``` In our tests a `1K` image took 47 seconds, a `2K` edit with one reference 40 seconds, and a `1K` layer decomposition that returned four images 39 seconds. Larger splits can take several minutes. ## Errors Requests rejected before a task is created return an HTTP error with an `error` object and are not charged. A task that fails after acceptance returns HTTP 200 when queried, with `status: "failed"` and an `error` object. See the [shared error catalog](https://seedrouter.ai/docs/api/errors) for codes, HTTP statuses, and retry guidance. ```json { "id": "task_...", "model": "seedream-5-5", "status": "failed", "error": { "code": 60001, "message": "The request was rejected by the content policy. Please revise the prompt or input images." } } ``` If submission itself times out, check your tasks before submitting again: the first request may have been accepted. ## Tips * Start at `1K` or `1.5K` to iterate; `1.5K` costs the same as `1K`. * Use exact pixels for a fixed shape, such as `2560x1440` for 16:9 at 2K. * Every reference costs money: send only the images the edit needs. * For layer decomposition, set `max_images` close to the number of elements you expect; the reservation follows it. * When you mainly want the text, leave `prompt` out of a split with `text_recognition` on. ## Related * [Seedream 5.5 Playground and pricing](https://seedrouter.ai/models/seedream-5-5) * [Seedream 5.0 Pro API](https://seedrouter.ai/docs/seedream-5-0-pro) * [Download OpenAPI](https://seedrouter.ai/docs/seedream-5-5.openapi.json) * [Copyable Markdown](https://seedrouter.ai/docs/seedream-5-5.md)