# Doubao Seedream 5.0 Pro 图层拆分

> 使用 Seedream 5.0 Pro 自动拆分、定向拆分或编辑图片图层，并读取图层位置元数据

图层拆分仍使用 `POST /api/v3/images/generations`，兼容火山方舟图片生成 API 的请求与响应契约，并通过 `layer_decomposition: true` 开启。响应包含一张基础图和最多 16 个图层，`data` 最多包含 17 项。

<CardGroup cols={2}>
  <Card title="自动完整拆分" icon="wand-magic-sparkles">
    不传 `prompt`，自动识别并拆分图片中的主要元素
  </Card>
  <Card title="定向拆分" icon="bullseye">
    传入 `prompt`，描述希望拆出的对象或图层
  </Card>
  <Card title="图层编辑" icon="pen-to-square">
    传入 `prompt`，描述需要修改的图层及编辑目标
  </Card>
  <Card title="完整图层结果" icon="layer-group">
    返回基础图、透明 PNG 图层及每层的位置和说明
  </Card>
</CardGroup>

## 输入限制

| 项目 | 限制 |
| --- | --- |
| `image` | **必须且只能输入 1 张**，可传字符串或仅含一项的字符串数组 |
| 输入格式 | **png 或 jpeg**（也接受 jpg 别名） |
| 文件大小 | **不超过 30 MB** |
| 输入宽高 | 宽和高均 **大于 14 px** |
| 输入总像素 | **[262144, 36000000]** |
| 输入宽高比 | **[1/16, 16]** |
| `prompt` | 可选；省略时自动完整拆分，填写时用于定向拆分或图层编辑 |
| `size` | `auto`（默认）、`1K`、`1.5K`、`2K` |
| 显式 `宽x高` | **不支持** |
| 最大输出数 | **17 项**：1 张基础图 + 最多 16 个图层 |

`size: "auto"` 会保持原图宽高比：原图位于支持的 1K–2K 范围时尽量保持原分辨率，低于范围时上采样，高于范围时限制到支持的上限。

<Warning>
图层拆分采用完整结果语义：任一图层生成失败，整个请求都会失败，不返回部分成功结果。
</Warning>

## 请求参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | string | 是 | — | 固定为 `doubao-seedream-5-0-pro-260628` |
| `image` | string / string[] | 是 | — | 一张非空的 png 或 jpeg 图片；也接受 jpg 别名 |
| `layer_decomposition` | boolean | 是 | — | 必须为 `true` |
| `prompt` | string | 否 | — | 省略时自动完整拆分；填写时定向拆分或编辑 |
| `size` | string | 否 | `auto` | `auto` / `1K` / `1.5K` / `2K` |
| `optimize_prompt_options.mode` | string | 否 | `standard` | `standard` 或 `fast` |
| `output_format` | string | 否 | `jpeg` | 基础图格式：`jpeg` 或 `png` |
| `background` | string | 否 | `opaque` | `opaque` 或 `transparent`；传 `transparent` 时必须同时传 `output_format: "png"` |
| `response_format` | string | 否 | `url` | `url` 或 `b64_json` |
| `watermark` | boolean | 否 | `true` | 是否添加“AI 生成”水印 |
| `stream` | boolean | 否 | `false` | 仅接受 `false`，调用仍为同步；`true` 会返回参数错误 |

`size` 的枚举匹配不区分大小写，建议使用表中的规范写法。图层数量由模型决定，不能传 `n`；也不能传 `sequential_image_generation`、`sequential_image_generation_options` 或 `tools`。接口仅支持同步调用，`stream: true` 会返回参数错误，`stream: false` 可接受但不会改变同步行为。

## 请求示例

<CodeGroup>

```bash 自动完整图层拆分（不传 prompt）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "image": "https://example.com/images/poster.png",
    "layer_decomposition": true,
    "size": "auto",
    "response_format": "url"
  }'
```

```bash 定向图层拆分（传入 prompt）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "分别拆出标题文字、前景人物和背景装饰",
    "image": "https://example.com/images/poster.png",
    "layer_decomposition": true,
    "size": "2K",
    "output_format": "jpeg"
  }'
```

```bash 图层编辑（cURL）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "将标题文字改为金色立体字，并保留其他可编辑图层",
    "image": "https://example.com/images/poster.png",
    "layer_decomposition": true,
    "size": "1.5K",
    "output_format": "png"
  }'
```

</CodeGroup>

## 输出规则

| 输出项 | 格式 | 位置 |
| --- | --- | --- |
| 基础图 | 由 `output_format` 决定，默认 jpeg | `data[0]`，`z_index: 0` |
| 拆分图层 | **始终为带透明通道的 PNG** | 后续 `data[]`，`z_index` 从 1 递增 |

当 `response_format: "url"` 时，每个输出项使用 `url`，链接在生成后 **24 小时**内有效；当值为 `b64_json` 时，每个输出项使用 `b64_json`。

## 响应字段

顶层响应包含 `model`、`created`、`data` 与 `usage`。`data[]` 使用统一的输出项结构：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `url` | string | `response_format: "url"` 时返回 |
| `b64_json` | string | `response_format: "b64_json"` 时返回 |
| `size` | string | 当前输出项的实际尺寸，格式为 `宽x高` |
| `output_format` | string | 基础图由请求决定；拆分图层始终为 `png` |
| `z_index` | integer | 基础图为 0，后续图层从 1 递增 |
| `bounding_box.absolute` | integer[4] | `[left, top, right, bottom]`，相对于基础输出图的像素坐标 |
| `bounding_box.normalized` | integer[4] | `[left, top, right, bottom]`，每个值位于 **0..1000** |
| `name` | string | 图层名称 |
| `description` | string | 图层内容说明 |

<Warning>
两个坐标范围不可合并：交互编辑提示词中的 `<point>` 与 `<bbox>` 使用 **0..999**；图层响应的 `bounding_box.normalized` 使用 **0..1000**。
</Warning>

`usage` 包含 `input_images`、`generated_images`、`output_tokens` 和 `total_tokens`。`output_tokens` 为各输出图片像素总和除以 256 后取整；此接口中 `total_tokens` 与 `output_tokens` 一致。

```json 图层拆分成功响应
{
  "model": "doubao-seedream-5-0-pro-260628",
  "created": 1784696685,
  "data": [
    {
      "url": "https://example.com/generated/base.jpeg",
      "size": "2048x2048",
      "output_format": "jpeg",
      "z_index": 0
    },
    {
      "url": "https://example.com/generated/layer-1.png",
      "size": "1273x265",
      "output_format": "png",
      "z_index": 1,
      "bounding_box": {
        "absolute": [383, 120, 1655, 384],
        "normalized": [187, 59, 808, 188]
      },
      "name": "标题文字",
      "description": "黄色大号衬线字体的标题文字"
    }
  ],
  "usage": {
    "input_images": 1,
    "generated_images": 2,
    "output_tokens": 17701,
    "total_tokens": 17701
  }
}
```

<Note>
基础图通常不包含 `bounding_box`、`name` 与 `description`；这些字段用于描述后续拆分图层。
</Note>

## 相关文档

<CardGroup cols={2}>
  <Card title="图片生成与编辑" icon="image" href="/api-capabilities/seedream/image-generation">
    查看普通模式参数与透明背景条件
  </Card>
  <Card title="交互编辑" icon="crosshairs" href="/api-capabilities/seedream/interactive-editing">
    查看提示词坐标格式与示例
  </Card>
  <Card title="能力概览" icon="circle-info" href="/api-capabilities/seedream/overview">
    查看普通模式与图层模式差异
  </Card>
  <Card title="API Reference" icon="code" href="/api-reference/seedream/create-image">
    查看统一端点的条件请求结构
  </Card>
</CardGroup>