> ## 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

> 通过 MixRoute 调用 Seedream 5.5，支持文生图、参考图编辑、透明 PNG 和图层拆分。

Seedream 5.5 是字节跳动的图像创作与编辑模型。使用 `doubao-seedream-5-5-261028` 调用文生图、参考图编辑、透明背景生成及可编辑图层拆分。

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

向图片生成接口发送 JSON，请求头为 `Authorization: Bearer $MIXROUTE_API_KEY` 和 `Content-Type: application/json`。参数直接放在顶层，不包进 `metadata`。参考图编辑和图层拆分也使用这个接口，不使用 `/v1/images/edits` 或 Chat Completions。

> [!WARNING]
>
> MixRoute 的所有请求都必须提供 `prompt`，图层拆分也不例外。即使上游示例将其标为可选，也不能省略。

## 请求参数

| 字段 | 类型 | 说明 |
| - | - | - |
| `model` | string | 必填，使用 `doubao-seedream-5-5-261028`。 |
| `prompt` | string | 必填的生图描述或拆分指令。支持中文、英文、日文、韩文等多语言。建议中文不超过 300 字，这是建议长度，不是硬性校验上限。 |
| `image` | string / string\[] | 生成时可选，拆分时必填。可访问的图片 URL 或 Base64 data URL，也可用字符串数组。生成最多接受 10 张参考图；拆分只能传 1 张。 |
| `size` | string | 生成：`1K`、`1.5K`、`2K`（默认）或 `宽x高`。拆分：`1K`、`1.5K`、`2K`、`auto`（默认），不支持自定义像素尺寸。 |
| `output_format` | string | `png`（默认）或 `jpeg`。拆分时仅控制底图格式，各独立图层始终输出 PNG。 |
| `background` | string | 仅用于生成：`auto`（默认）、`transparent` 或 `opaque`。透明输出必须使用 PNG。拆分时必须省略整个字段。 |
| `response_format` | string | `url`（默认）或 `b64_json`。生成链接有效期为 24 小时，请及时保存图片。 |
| `watermark` | boolean | 默认 `true`，在右下角添加 AI 生成水印；传 `false` 关闭。 |
| `safety_identifier` | string | 可选的终端用户标识，最多 64 个字符。建议使用哈希标识，不直接传个人信息。 |
| `layer_decomposition` | boolean | 传 `true` 将一张输入图拆成底图与透明图层。普通生成省略或设为 `false`。 |
| `layer_decomposition_options` | object | 可选的拆分配置，仅在 `layer_decomposition` 为 `true` 时传入。 |
| `layer_decomposition_options.max_images` | integer | 2-100 的整数，默认 30。限制包括底图在内的输出总张数，不是仅限制图层数。 |
| `layer_decomposition_options.text_recognition` | boolean | 传 `true` 请求规整文字图层的富文本 OCR；并非每个图层都会返回 OCR。 |

## 图片、尺寸与限制

* 普通生成每次只返回 1 张图片，`n` 不控制输出数量。不支持流式、组图或联网搜索，请省略 `stream`、`sequential_image_generation` 及搜索工具字段。
* 单张参考图不超过 30 MB，宽高比为 1:16 至 16:1。Base64 data URL 的格式名必须小写，例如 `data:image/png;base64,...`。
* 生成时使用分辨率档位，可在 `prompt` 中描述宽高比；使用 `宽x高` 时用小写 `x`，总像素须为 921,600-4,624,220，宽高比为 1:16 至 16:1，例如 `2880x1440`。像素限制指宽乘高，不是单边长度。
* 拆分只能输入 1 张 PNG 或 JPEG，总像素不少于 262,144（512 x 512）。`size: auto` 按输入尺寸与宽高比适配，不保证每个输出都保持原始像素尺寸，请读取各项 `data[].size`。
* 任一图层失败，整个拆分请求失败。提示词要求的输出数超过 `max_images` 时，部分要求拆出的元素可能缺失。

## 请求示例

将 `MIXROUTE_API_KEY` 设置为 MixRoute Key。发送请求前，将下方 `example.com` 输入地址替换为可访问的图片。

### 文生图

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

### 多图参考

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

### 透明 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
}'
```

### 图层拆分与 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 OpenAI SDK

安装 `openai` 包，设置 `MIXROUTE_API_KEY` 和 `SEEDREAM_IMAGE_URL`。Seedream 专有字段及分辨率值放在 SDK 的 `extra_body` 中；发送时会合并为顶层 JSON 字段，不会产生 `extra_body` 或 `metadata` 包装对象。示例关闭自动重试，避免盲目重复生图请求。

```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", {}))
```

## 返回字段

| 字段 | 说明 |
| - | - |
| `data[].url / data[].b64_json` | 图片 URL 或 Base64 数据，由 `response_format` 决定。 |
| `data[].size` | `宽x高` 格式的实际像素尺寸，不同图层可能不同。 |
| `data[].output_format` | 实际 `png` 或 `jpeg` 格式；拆出的独立图层始终为 PNG。 |
| `data[].background` | 实际透明状态：`transparent` 或 `opaque`，不是请求值 `auto`。 |
| `data[].z_index` | 仅拆分返回。底图为 0，图层从 1 开始，数字越大越靠上。 |
| `data[].name / data[].description` | 仅拆分返回，由模型生成的图层名称和描述。 |
| `data[].bounding_box` | 仅图层返回，底图不包含。`absolute` 是底图像素坐标 `[left, top, right, bottom]`，`normalized` 使用相同顺序、0-1000 的相对坐标。 |
| `data[].text_recognition` | 开启 OCR 且图层包含规整文字时返回。包括完整文本、逐行位置与样式，如近似字体、颜色、粗体和斜体。 |
| `usage.input_images / usage.generated_images` | 输入图数量和成功生成的图片数量。拆分的生成数量包含底图与每个独立图层。 |

以下为包含 1 张底图和 1 个图层的示意响应节选：

```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
  }
}
```

## 还原图层

以 `z_index: 0` 的底图为画布，按 `bounding_box.absolute` 将各图层缩放到 `(right - left) x (bottom - top)`，放置在 `(left, top)`，再按 `z_index` 从小到大进行透明合成。图层原生 `size` 可能与放置尺寸不同。OCR 提供文字信息，实际文字编辑仍由你的应用完成。

## 计费

输入图和成功输出图分别按张计费。输出档位按每张图实际宽乘高决定，不只看请求中的尺寸名称。以下美元标准价与当前公开报价一致，账号及路由实际价格以[模型广场](https://console.mixroute.ai/models)为准。

| 计价项 | 标准价：美元/张 |
| - | - |
| 输入图 | 0.0075 |
| 输出图不超过 2,610,000 像素 | 0.0195 |
| 输出图超过 2,610,000 像素 | 0.0345 |

* 每张参考图或待拆分图都算输入图。底图和每个成功生成的图层各算一张输出图，按各自像素档计价；未成功输出的图不计费。
* 图层拆分会按 `max_images` 预扣额度，完成后按实际输出张数结算，退回未使用的预扣部分。余额有限时可调小该上限。
* 例如：1 张输入图，成功输出 3 张且每张均超过 2,610,000 像素，标准价为 `0.0075 + 3 * 0.0345 = 0.111` 美元。不同尺寸的图层可能属于不同价格档，实际扣费请查看消费日志。

## 常见错误

| 字段 | 说明 |
| - | - |
| `prompt is required` | 补充非空 `prompt`，图层拆分也必须传。 |
| `layer_decomposition_options.max_images must be an integer between 1 and 128` | 传 2-100 的整数。网关报错可能写 1-128，但这不是上游实际支持范围。 |
| `layer_decomposition must be a boolean` | 使用 JSON 布尔值 `true` 或 `false`，不要传字符串。 |
| `stream: true` | 省略 `stream`，Seedream 5.5 不支持流式输出。 |
| `output_format: jpeg + background: transparent` | 透明生成使用 PNG；拆分时省略 `background`。 |

[模型介绍](https://mixroute.ai/docs/zh-Hans/model-api/bytedance/doubao-seedream-5-5.md)


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