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

# Seedream 5.0 Pro · 图生图

> Seedream 5.0 Pro 图生图参数、限制与可直接复制的调用示例

## 简介

传入参考图片和编辑指令，支持单图编辑、多图融合、交互编辑、透明图和图层拆分。普通编辑输出 1 张图片；图层拆分返回底图和多个图层。

## 接口与认证

```http theme={null}
POST https://api.gravitex.ai/v1/images/generations
```

使用 `Authorization: Bearer sk-xxxxxxxxxx` 和 `Content-Type: application/json`。图生图也可使用 `/v1/images/edits`，JSON 请求体相同。认证和接口规则见 [参数与计费](https://docs.gravitex.ai/cn/api-reference/endpoint/seedream-5.0.md#认证)。

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | `dola-seedream-5-0-pro-260628` |
| `prompt` | string | 编辑必填 | 描述如何修改参考图；图层拆分时可省略 |
| `image` | string / string\[] | 是 | 参考图片 URL 或 Base64；普通编辑最多 10 张，图层拆分只能 1 张 |
| `size` | string | 否 | 普通编辑默认 `2K`，支持 `1K`、`1.5K`、`2K` 或自定义 `宽x高`；图层拆分默认 `auto` |
| `output_format` | string | 否 | `jpeg` / `png`，默认 `jpeg`；透明图使用 `png` |
| `response_format` | string | 否 | `url` / `b64_json`，默认 `url` |
| `watermark` | boolean | 否 | 默认 `true`；不添加水印时传 `false` |
| `background` | string | 否 | 默认 `opaque`，支持 `transparent`；透明图仅允许 1 张带透明通道的参考图；图层拆分不能传此字段 |
| `optimize_prompt_options` | object | 否 | `mode` 支持 `standard`（默认）/ `fast` |
| `layer_decomposition` | boolean | 否 | 默认 `false`；传 `true` 开启图层拆分 |

`n` 传 `1` 或不传；需要多张普通生成结果时请分别请求。`safety_identifier`、完整默认值和参数解释见 [通用参数](https://docs.gravitex.ai/cn/api-reference/endpoint/seedream-5.0.md#请求参数)。两版均不支持 `quality`、组图、流式输出与联网搜索。

### prompt

用于描述生成内容，或指定图层拆分意图。

* **图片生成场景**：必填。图生图时，`prompt` 同时说明怎么使用和修改参考图。
* **图层拆分场景**：可选。用于指定要拆出的元素；不传时模型自动识别图中所有主要元素并拆成独立图层。
* **字数建议**：中文不超过 300 字，英文不超过 600 词。字数过多时信息容易分散，模型可能忽略细节。

```json theme={null}
{
  "prompt": "未来城市夜景，电影海报风格，高细节，蓝紫色霓虹灯"
}
```

**交互编辑**：可以在提示词里用 `<bbox>x1 y1 x2 y2</bbox>` 指定区域，官方示例用的是 `[0, 1000]` 的归一化坐标（左上角为原点）；也可以直接在参考图上画框、箭头或草图，再在提示词里说明怎么处理标记区域。

```json theme={null}
{
  "prompt": "把 <bbox>120 560 380 900</bbox> 区域里的杯子换成一盆绿植，其余内容保持不变"
}
```

### image

参考图，支持单个字符串或字符串数组。每张图可以是：

* **图片 URL**：必须能被服务端访问，不能只在本地浏览器有效。
* **Base64**：格式为 `data:image/<图片格式>;base64,<Base64 编码>`，`<图片格式>` 需小写，如 `data:image/png;base64,iVBORw0...`。

```json theme={null}
{
  "image": "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg"
}
```

```json theme={null}
{
  "image": [
    "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
    "https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=1024&fm=jpg"
  ]
}
```

**普通编辑场景**（必填，最多 10 张）：

| 限制项 | 要求 |
| - | - |
| 格式 | jpeg、png、webp、bmp、tiff、gif、heic、heif |
| 宽高比（宽 / 高） | \[1/16, 16] |
| 宽、高 | 均大于 14 px |
| 单张大小 | 不超过 30 MB |
| 总像素（宽 × 高） | \[196, 6000×6000] |

**图层拆分场景**（必填，且只能传 1 张，传多张报错）：

| 限制项 | 要求 |
| - | - |
| 格式 | png、jpeg |
| 宽高比（宽 / 高） | \[1/16, 16] |
| 单张大小 | 不超过 30 MB |
| 总像素（宽 × 高） | \[512×512, 6000×6000] |

> [!NOTE]
>
> 总像素是对宽 × 高乘积的限制，不是对宽或高单独限制。

### size

普通编辑的尺寸规则见 [通用尺寸说明](https://docs.gravitex.ai/cn/api-reference/endpoint/seedream-5.0.md#size)。图层拆分仅支持 `1K`、`1.5K`、`2K`、`auto`，默认 `auto`；不能传自定义像素尺寸。底图和图层的缩放规则见 [尺寸说明](https://docs.gravitex.ai/cn/api-reference/endpoint/seedream-5.0.md#size)。

### background

控制输出图片是否带透明通道。

| 取值 | 说明 |
| - | - |
| `opaque` | 输出不带透明通道的 RGB 图，默认值 |
| `transparent` | 输出带透明通道的 RGBA 图 |

> [!WARNING]
>
> * 该模型**不支持文生透明图**；用 `transparent` 时只能传 **1 张**参考图，且参考图**必须带透明通道**。
> * `transparent` 不能和 `output_format: "jpeg"` 同时用，否则报错；请同时传 `output_format: "png"`。
> * 图层拆分场景不能传 `background`，传了报错。

### layer\_decomposition

是否开启图层拆分。

| 取值 | 说明 |
| - | - |
| `true` | 图层拆分模式：把输入图拆成 1 张底图和多个图层 |
| `false` | 图片生成模式，默认值 |

开启后，模型会把图片中的主体、背景、文字等内容拆成 1 张底图和**最多 16 个**可独立编辑的图层，每个图层都是带透明通道的 PNG。

> [!NOTE]
>
> * `image` 必填，且只能传 1 张。
> * 任一图层生成失败，整个请求失败，不支持部分成功。
> * 提示词要求的图层数超过上限时，部分图层信息可能丢失。
> * 响应 `data` 中会返回每个图层的叠放顺序（`z_index`）、名称（`name`）、描述（`description`）和边界框（`bounding_box`），见 [返回字段](#返回字段)。
> * 底图和每个图层都算一张生成图片，计入 `usage.generated_images`。

## 调用示例

每个示例提供可直接复制的完整 JSON 请求 body 和对应 cURL。图片输入使用无需登录的公网 URL；使用 cURL 时，请将 `sk-xxxxxxxxxx` 替换为自己的 API Key。响应中的图片 URL 仅用于展示返回结构，不是请求素材。

### 单图生图

```json 请求 body theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "prompt": "保留参考图中狗的外形，将它绘制成水彩插画",
  "image": "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
  "size": "2K"
}
```

```bash cURL theme={null}
curl --location 'https://api.gravitex.ai/v1/images/generations' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "dola-seedream-5-0-pro-260628",
    "prompt": "保留参考图中狗的外形，将它绘制成水彩插画",
    "image": "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
    "size": "2K"
  }'
```

### 多图融合

```json 请求 body theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "prompt": "将图 1 中的狗放到图 2 的湖畔场景中，保持狗的外形，统一光线与透视",
  "image": [
    "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
    "https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=1024&fm=jpg"
  ],
  "size": "2K"
}
```

```bash cURL theme={null}
curl --location 'https://api.gravitex.ai/v1/images/generations' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "dola-seedream-5-0-pro-260628",
    "prompt": "将图 1 中的狗放到图 2 的湖畔场景中，保持狗的外形，统一光线与透视",
    "image": [
      "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
      "https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=1024&fm=jpg"
    ],
    "size": "2K"
  }'
```

### 交互编辑

```json 请求 body theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "prompt": "只编辑 <bbox>0 0 1000 300</bbox> 区域，将该区域的背景改为浅蓝色，保持狗和其余区域不变",
  "image": "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
  "size": "2K",
  "output_format": "png"
}
```

```bash cURL theme={null}
curl --location 'https://api.gravitex.ai/v1/images/generations' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "dola-seedream-5-0-pro-260628",
    "prompt": "只编辑 <bbox>0 0 1000 300</bbox> 区域，将该区域的背景改为浅蓝色，保持狗和其余区域不变",
    "image": "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
    "size": "2K",
    "output_format": "png"
  }'
```

### 透明图

```json 请求 body theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "prompt": "将参考图中的彩色图形改为金属质感，保留透明背景",
  "image": "https://raw.githubusercontent.com/pnggroup/libpng/libpng16/pngtest.png",
  "background": "transparent",
  "output_format": "png"
}
```

```bash cURL theme={null}
curl --location 'https://api.gravitex.ai/v1/images/generations' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "dola-seedream-5-0-pro-260628",
    "prompt": "将参考图中的彩色图形改为金属质感，保留透明背景",
    "image": "https://raw.githubusercontent.com/pnggroup/libpng/libpng16/pngtest.png",
    "background": "transparent",
    "output_format": "png"
  }'
```

### 图层拆分

```json 请求 body theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "prompt": "将参考图中的天空、山体、湖水和前景分别拆成独立图层",
  "image": "https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=1024&fm=jpg",
  "layer_decomposition": true,
  "size": "2K",
  "output_format": "jpeg"
}
```

```bash cURL theme={null}
curl --location 'https://api.gravitex.ai/v1/images/generations' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "dola-seedream-5-0-pro-260628",
    "prompt": "将参考图中的天空、山体、湖水和前景分别拆成独立图层",
    "image": "https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=1024&fm=jpg",
    "layer_decomposition": true,
    "size": "2K",
    "output_format": "jpeg"
  }'
```

## 成功返回

普通编辑的基础响应与文生图一致，`usage.input_images` 按实际输入图片数统计，见 [基础响应](https://docs.gravitex.ai/cn/api-reference/endpoint/seedream-5.0.md#成功返回)。以下为图层拆分响应的节选，仅展示底图和 1 个图层。`usage` 为完整响应的用量，因此 `generated_images` 不等于本节选中的图片数；URL 仅作结构示意：

```json theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "created": 1784696685,
  "data": [
    {
      "url": "https://example.com/base.jpeg",
      "size": "2048x2048",
      "output_format": "jpeg",
      "z_index": 0
    },
    {
      "url": "https://example.com/layer-1.png",
      "size": "1273x265",
      "output_format": "png",
      "z_index": 1,
      "bounding_box": {
        "absolute": [383, 120, 1655, 384],
        "normalized": [187, 59, 808, 188]
      },
      "name": "Seedream标题文字",
      "description": "黄色大号衬线字体的Seedream标题文字"
    }
  ],
  "usage": {
    "input_images": 1,
    "generated_images": 8,
    "output_tokens": 23107,
    "total_tokens": 23107
  }
}
```

### 返回字段

除 [基础响应字段](https://docs.gravitex.ai/cn/api-reference/endpoint/seedream-5.0.md#返回字段) 外，图层拆分额外返回：

| 字段 | 类型 | 说明 |
| - | - | - |
| `data[].z_index` | integer | 图层叠放顺序，底图为 `0`，图层从 `1` 递增，越大越靠上（仅图层拆分） |
| `data[].name` | string | 图层名称，由模型生成（仅图层拆分） |
| `data[].description` | string | 图层描述，比 `name` 更详细（仅图层拆分） |
| `data[].bounding_box.absolute` | integer\[4] | 图层在输出底图中的像素坐标 `[left, top, right, bottom]`；底图不返回（仅图层拆分） |
| `data[].bounding_box.normalized` | integer\[4] | 同上，换算到 `[0, 1000]` 的归一化坐标；底图不返回（仅图层拆分） |

> [!NOTE]
>
> **还原图层**：用 `absolute` 坐标时，把图层缩放到 `(right - left) × (bottom - top)`，放到底图的 `(left, top)`；用 `normalized` 坐标还原到 `W × H` 的任意画布时，左上角为 `(left / 1000 × W, top / 1000 × H)`。多个图层按 `z_index` 从小到大叠放。

> [!WARNING]
>
> `data[].url` 是临时地址，24 小时后失效。收到响应后请立即下载并转存到自己的对象存储。

## 计费与错误处理

参考图与输出图分别计费；图层拆分的底图和每个图层分别算 1 张输出图。详细价格和示例见 [计费说明](https://docs.gravitex.ai/cn/api-reference/endpoint/seedream-5.0.md#计费说明)；排查参数、图片读取等问题见 [错误处理](https://docs.gravitex.ai/cn/api-reference/endpoint/seedream-5.0.md#错误处理)。


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