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

See the model page for current prices.

Quick example

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"
  }'

Endpoint

POST https://api.seedrouter.ai/v1/images/generations

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

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

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).

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").

{
  "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:

{
  "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.

{
  "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 for current rates. Seedream 5.5 is priced per output image by pixel tier, plus every reference image:

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:

{"id": "task_...", "model": "seedream-5-5", "status": "processing", "created_at": 1794323757}

Get the task

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

{
  "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:

{
  "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 for codes, HTTP statuses, and retry guidance.

{
  "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
• Seedream 5.0 Pro API
• Download OpenAPI
• Copyable Markdown