> ## Documentation Index
> Fetch the complete documentation index at: https://mixroute.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedream 5.5

> Seedream 5.5 image generation, reference-image editing, transparent PNGs and layer decomposition through MixRoute.

Seedream 5.5 is ByteDance's image creation and editing model. Use `doubao-seedream-5-5-261028` for text-to-image, reference-image editing, transparent backgrounds and decomposition into editable layers.

`POST https://api.mixroute.ai/v1/images/generations`

Send JSON to the image-generation endpoint with `Authorization: Bearer $MIXROUTE_API_KEY` and `Content-Type: application/json`. Parameters are top-level fields, not a `metadata` wrapper. Reference-image editing and layer decomposition use this same endpoint, not `/v1/images/edits` or Chat Completions.

> [!WARNING]
>
> On MixRoute, `prompt` is required for every request, including layer decomposition. Do not omit it even if an upstream example treats it as optional.

## Request parameters

| Field | Type | Description |
| - | - | - |
| `model` | string | Required. Use `doubao-seedream-5-5-261028`. |
| `prompt` | string | Required image description or decomposition instructions. Supports multiple languages, including Chinese, English, Japanese and Korean. For Chinese, no more than 300 characters is recommended, not a hard validation limit. |
| `image` | string / string\[] | Optional for generation; required for decomposition. An accessible image URL or Base64 data URL, or an array of these strings. Generation accepts up to 10 reference images; decomposition accepts exactly one. |
| `size` | string | Generation: `1K`, `1.5K`, `2K` (default), or `widthxheight`. Decomposition: `1K`, `1.5K`, `2K`, `auto` (default); custom pixel dimensions are not supported in this mode. |
| `output_format` | string | `png` (default) or `jpeg`. For decomposition this controls the base image only; every separate layer is PNG. |
| `background` | string | Generation only: `auto` (default), `transparent` or `opaque`. Transparent output requires PNG. Omit this field entirely during decomposition. |
| `response_format` | string | `url` (default) or `b64_json`. Generated URLs are temporary and valid for 24 hours; save the images promptly. |
| `watermark` | boolean | Defaults to `true`, adding an AI-generated watermark in the lower-right corner. Set `false` to disable it. |
| `safety_identifier` | string | Optional end-user identifier, at most 64 characters. Prefer a hashed identifier over personal information. |
| `layer_decomposition` | boolean | Set `true` to decompose one input image into a base image and transparent layers. Omit or set `false` for ordinary generation. |
| `layer_decomposition_options` | object | Optional decomposition settings. Supply only when `layer_decomposition` is `true`. |
| `layer_decomposition_options.max_images` | integer | Integer from 2 to 100, default 30. Caps the total output count including the base image, not the layer count alone. |
| `layer_decomposition_options.text_recognition` | boolean | Set `true` to request rich-text OCR for regular text layers. OCR is not returned for every layer. |

## Images, sizes and limits

* Generation returns one image per request. `n` does not control the output count. Streaming, sequential image generation and web search are not supported; omit `stream`, `sequential_image_generation` and search-tool fields.
* Each reference image must be at most 30 MB with an aspect ratio from 1:16 to 16:1. Base64 URLs use a lowercase format name, for example `data:image/png;base64,...`.
* For generation with a resolution preset, describe the desired aspect ratio in `prompt`. For `widthxheight`, use a lowercase `x`, a total of 921,600-4,624,220 pixels and an aspect ratio from 1:16 to 16:1; `2880x1440` is valid. These are total-pixel limits, not per-edge limits.
* Decomposition requires exactly one PNG or JPEG image with at least 262,144 total pixels (512 x 512). `size: auto` adapts to input dimensions and aspect ratio; do not assume every output retains its original pixel dimensions. Read each returned `data[].size`.
* If any layer fails, the entire decomposition request fails. Asking for more outputs than `max_images` permits can leave requested elements out.

## Request examples

Set `MIXROUTE_API_KEY` to your MixRoute key. Replace the `example.com` input URLs below with accessible images before sending requests.

### Text-to-image

```bash theme={null}
curl --request POST "https://api.mixroute.ai/v1/images/generations" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "doubao-seedream-5-5-261028",
  "prompt": "A lake below snowy mountains in morning mist, realistic photography, 16:9 landscape.",
  "size": "2K",
  "watermark": false
}'
```

### Multiple reference images

```bash theme={null}
curl --request POST "https://api.mixroute.ai/v1/images/generations" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "doubao-seedream-5-5-261028",
  "prompt": "Replace the clothing of the person in image 1 with the outfit in image 2.",
  "image": [
    "https://example.com/person.png",
    "https://example.com/outfit.png"
  ],
  "size": "1K"
}'
```

### Transparent PNG

```bash theme={null}
curl --request POST "https://api.mixroute.ai/v1/images/generations" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "doubao-seedream-5-5-261028",
  "prompt": "A red ceramic mug as a clean product cutout with a transparent background.",
  "size": "1.5K",
  "output_format": "png",
  "background": "transparent",
  "response_format": "url",
  "watermark": false
}'
```

### Layer decomposition with OCR

```bash theme={null}
curl --request POST "https://api.mixroute.ai/v1/images/generations" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "doubao-seedream-5-5-261028",
  "prompt": "Decompose the image into separate layers: title text, person, and background.",
  "image": "https://example.com/poster.png",
  "layer_decomposition": true,
  "layer_decomposition_options": {
    "max_images": 8,
    "text_recognition": true
  },
  "size": "2K",
  "output_format": "png",
  "response_format": "url",
  "watermark": false
}'
```

## Python with the OpenAI SDK

Install the `openai` package and set `MIXROUTE_API_KEY` and `SEEDREAM_IMAGE_URL`. Put Seedream-specific fields and resolution values in the SDK's `extra_body`; they become top-level JSON fields on the wire, not an `extra_body` or `metadata` object. Automatic retries are disabled to avoid blindly repeating generation requests.

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.mixroute.ai/v1",
    api_key=os.environ["MIXROUTE_API_KEY"],
    max_retries=0,
    timeout=180.0,
)
response = client.images.generate(
    model="doubao-seedream-5-5-261028",
    prompt="Decompose the image into separate layers: title text, person, and background.",
    response_format="url",
    extra_body={
        "image": os.environ["SEEDREAM_IMAGE_URL"],
        "size": "auto",
        "layer_decomposition": True,
        "layer_decomposition_options": {"max_images": 8, "text_recognition": True},
        "output_format": "png",
        "watermark": False,
    },
)
result = response.model_dump()
if result.get("error"):
    raise RuntimeError(result["error"])
images = result.get("data")
if not images:
    raise ValueError("No output images returned")
for item in images:
    if item.get("error") or not item.get("url"):
        raise ValueError("An output image is missing or failed")
    print(item.get("z_index"), item["url"], item.get("size"))
print(result.get("usage", {}))
```

## Response fields

| Field | Description |
| - | - |
| `data[].url / data[].b64_json` | Output image URL or Base64 data, according to `response_format`. |
| `data[].size` | Actual pixel dimensions in `widthxheight` format. Different layers can have different dimensions. |
| `data[].output_format` | Actual `png` or `jpeg` format. Decomposed layers are always PNG. |
| `data[].background` | Actual transparency: `transparent` or `opaque`, rather than the request value `auto`. |
| `data[].z_index` | Decomposition only. The base image is 0; layers start at 1. Larger indexes are placed above smaller indexes. |
| `data[].name / data[].description` | Decomposition only. Model-generated layer name and description. |
| `data[].bounding_box` | Layer only; absent on the base image. `absolute` is `[left, top, right, bottom]` in base-image pixels. `normalized` uses the same order on a 0-1000 scale. |
| `data[].text_recognition` | Returned when OCR is requested and the layer contains regular text. Includes full text and line-level positions/styles such as approximate font, color, bold and italic attributes. |
| `usage.input_images / usage.generated_images` | Number of input images and successfully generated images. In decomposition, generated images include the base image and each separate layer. |

Illustrative decomposition response excerpt with one base image and one layer:

```json theme={null}
{
  "data": [
    {
      "url": "https://example.com/base.png",
      "size": "2048x2048",
      "output_format": "png",
      "z_index": 0,
      "background": "opaque"
    },
    {
      "url": "https://example.com/person-layer.png",
      "size": "1647x2546",
      "output_format": "png",
      "z_index": 1,
      "bounding_box": {
        "absolute": [
          474,
          372,
          1544,
          2048
        ],
        "normalized": [
          231,
          182,
          754,
          1000
        ]
      },
      "name": "Person",
      "description": "The person standing in the center.",
      "background": "transparent"
    }
  ],
  "usage": {
    "input_images": 1,
    "generated_images": 2
  }
}
```

## Reconstruct the image

Start with the base image (`z_index: 0`). For each layer, resize its pixels to `(right - left) x (bottom - top)` using `bounding_box.absolute`, position it at `(left, top)`, and alpha-composite in increasing `z_index` order. The layer's native `size` may differ from its placement dimensions. OCR describes text for your application to edit; it does not perform the editing itself.

## Billing

Input images and successful output images are billed separately. Output tiers depend on each image's actual width multiplied by height, not just the requested size label. The standard USD rates below match the current public pricing; account and route prices in the [Model Marketplace](https://console.mixroute.ai/models) take precedence.

| Item | Standard USD per image |
| - | - |
| Input image | 0.0075 |
| Output at or below 2,610,000 pixels | 0.0195 |
| Output above 2,610,000 pixels | 0.0345 |

* Each reference image or image being decomposed is an input image. The base image and every successfully generated layer are separate output images, each using its own pixel tier. Unsuccessful outputs are not charged.
* Decomposition reserves credit using `max_images` and settles against the actual output count, returning unused reserved credit. Use a smaller limit when balance is constrained.
* Example: one input and three successful output images, all above 2,610,000 pixels, cost `0.0075 + 3 * 0.0345 = 0.111` USD at the standard rates. Mixed-size layers can fall into different tiers. Check Usage Logs for the actual charge.

## Common errors

| Field | Description |
| - | - |
| `prompt is required` | Include a nonempty `prompt`, including in decomposition mode. |
| `layer_decomposition_options.max_images must be an integer between 1 and 128` | Use an integer from 2 to 100. A gateway error may mention 1-128, but that is not the upstream's supported range. |
| `layer_decomposition must be a boolean` | Use JSON booleans `true` or `false`, not strings. |
| `stream: true` | Omit `stream`; Seedream 5.5 does not support streaming. |
| `output_format: jpeg + background: transparent` | Use PNG for transparent generation. Omit `background` during decomposition. |

[Model introduction](https://mixroute.ai/docs/model-api/bytedance/doubao-seedream-5-5.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.