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

# Seedream 5.5 图像生成

> 支持文生图、最多 10 张参考图、透明背景，以及可调数量的图层拆分和文字 OCR。异步提交并查询任务结果。

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedream-5-5",
  "prompt": "An orange cat sticker with clean edges",
  "size": "2K",
  "background": "transparent",
  "output_format": "png"
}'
```

```python Python theme={null}
import requests

payload = {
  "model": "seedream-5-5",
  "prompt": "An orange cat sticker with clean edges",
  "size": "2K",
  "background": "transparent",
  "output_format": "png"
}
response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const payload = {
  "model": "seedream-5-5",
  "prompt": "An orange cat sticker with clean edges",
  "size": "2K",
  "background": "transparent",
  "output_format": "png"
};
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_example_seedream55"
    }
  ]
}
```

调用 `POST /v1/images/generations` 提交任务，从 `data[0].task_id` 获取任务 ID，再通过 `GET /v1/tasks/{task_id}` 查询结果。

## 模式选择

| 模式 | 触发方式 | 输入图 | 提示词 |
| - | - | - | - |
| 图片生成 | 默认 | 0–10 张 | 必填 |
| 图层拆分 | `layer_decomposition: true` | 恰好 1 张 | 可省略 |

## 认证

**Authorization** `string` *required*

使用 `Authorization: Bearer <token>`，其中 `<token>` 为你的 APIMart API Key。

## 请求参数

**model** `string` *required*

固定为 `seedream-5-5`。

**prompt** `string`

文生图和图生图必填。图层拆分可省略，模型会自动识别并拆分主体、文字和背景；也可传提示词描述拆分目标。

**image\_urls** `string[]`

图片生成最多 10 张参考图；图层拆分必须恰好 1 张。支持公网图片 URL 或图片 Base64 Data URI。本地文件可先通过[图片上传接口](https://docs.apimart.ai/cn/api-reference/uploads/images.md)上传，再传返回的 `url`。

参考图须为公网可访问的 `http(s)` 直链或 `data:image/<格式>;base64,…`，Data URI 中格式名使用小写。

* 支持 JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF；不支持 AVIF、JP2。
* 单张不超过 **30 MiB（31,457,280 字节）**，总像素不超过 **3600 万**。按宽 × 高判断，不是每条边都以 6000 为上限。
* 大小或像素超限时同步返回 HTTP 400。AVIF、JP2 可能在创建任务后由上游拒绝，任务失败后退款；请先转换格式再提交。

图片上传接口有独立的格式限制，以其文档为准；模型支持但上传接口不支持的格式，可使用公网直链或 Data URI。

**size** `string`

图片生成默认 `2K`，支持档位、宽高比或精确像素，具体写法见下文。图层拆分默认 `auto`，只支持 `1K` / `1.5K` / `2K` / `auto`，不能使用宽高比或精确像素。

图片生成时，`size: "auto"` 等同 `2K`；使用宽高比形式的 `size` 时，省略 `resolution` 也按 `2K`。精确像素写法不传 `resolution`，宽高须为正整数。

**resolution** `string`

图片生成时，支持 `1K` / `1.5K` / `2K`，与宽高比形式的 `size` 配合使用。图层拆分时，这是平台提供的 `size` 别名：优先使用 `size`，仅在省略 `size` 时使用 `resolution`；两者均未传时为 `auto`。图层模式的有效值为 `1K` / `1.5K` / `2K` / `auto`，比例或像素写法会同步返回 HTTP 400。不支持 `3K` / `4K`。

**background** `string`

图片生成支持 `auto`（默认）、`transparent`、`opaque`。文生图和图生图均可生成透明背景。透明背景必须输出 PNG，不能与 `output_format: "jpeg"` 同用。图层拆分时必须省略此字段，包括 `auto`。

**output\_format** `string` (default: png)

支持 `png`（默认）或 `jpeg`。图层拆分时仅控制底图格式，拆出的图层恒为透明 PNG。

**n** `integer`

只能为 `1`。图片生成每次输出一张；图层拆分的数量使用 `layer_decomposition_options.max_images` 控制。

**watermark** `boolean` (default: false)

是否添加水印，可选。

**optimize\_prompt\_options** `object`

只支持 `{"mode":"standard"}`。省略时，上游仍默认启用 `standard`，Seedream 5.5 无法关闭提示词优化。`disabled` / `none` / `off` 均被上游以 HTTP 400 拒绝，报错包含 `must be one of: standard`；`fast` 在平台入口直接返回 HTTP 400。

**layer\_decomposition** `boolean`

设置为 `true` 时将输入图拆成底图和透明图层。必须恰好提供一张输入图，且不能传 `background`；`output_format` 仅控制底图。

**layer\_decomposition\_options** `object`

仅在 `layer_decomposition: true` 时可传，否则返回 HTTP 400。

**请求参数**

**max\_images** `integer` (default: 30)

整数 `2`–`100`，默认 `30`；是本次输出图片总数上限，包含底图，不表示一定生成这么多张。

**text\_recognition** `boolean` (default: false)

可选布尔值。设为 `true` 时请求文字图层的富文本 OCR；只有可识别的规整文字层才可能返回 `text_recognition`，不能假定每层都有。

开启 OCR 后，传入 `prompt` 可能导致文字识别结果不返回。如主要需要 OCR，可尝试省略拆分提示词；这不能保证每次都返回 OCR，仍需按可选字段处理。

## 尺寸写法

| 写法 | 示例 | 规则 |
| - | - | - |
| 档位 | `"size": "2K"` | `1K` / `1.5K` / `2K`；图片生成默认 `2K`，模型按提示词选择比例。 |
| 宽高比 + 档位 | `"size": "16:9", "resolution": "1.5K"` | 仅用于图片生成；比例见下方列表，也接受 `16x9` 写法。 |
| 精确像素 | `"size": "2048x1152"` | 仅用于图片生成；总像素须在 921,600–4,624,220，宽/高须在 1/16–16。 |

支持的比例：`1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`3:2`、`2:3`、`21:9`、`2:1`、`1:2`。

精确尺寸按宽高乘积和比例校验。图层拆分只接受档位或 `auto`，不适用宽高比和精确像素写法。

### 图层拆分的尺寸行为

* 优先级：`size` → `resolution` → `auto`。`resolution` 是平台对 `size` 的另一种写法，上游只接收 `size`。例如同时传 `size: "1K"` 和 `resolution: "2K"` 时按 `1K`；只传 `resolution: "1.5K"` 时按 `1.5K`。

* 指定 `1K` / `1.5K` / `2K` 时，底图和每个图层都按所选档位输出，各自保持原比例。实测 `1K` 的一个底图为 `840×1248`，各图层也约为 105 万像素；这些是代表性结果，不是固定宽高。

* `auto` 按输入图原尺寸输出：低于 `1K` 的输入提升到 `1K`，高于 `2K` 的输入缩小到 `2K`。

## 请求示例

### 图生图与参考图融合

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedream-5-5",
  "prompt": "Combine the product in the first image with the setting in the second image",
  "image_urls": ["https://example.com/product.png", "https://example.com/setting.jpg"],
  "size": "16:9",
  "resolution": "1.5K",
  "output_format": "png"
}'
```

### 图层拆分与文字 OCR

示例请求最多输出 10 张图片，包含底图。`prompt` 可省略；图层模式下不传 `background`。请替换为实际可访问的图片地址。

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedream-5-5",
  "image_urls": ["https://example.com/poster.png"],
  "layer_decomposition": true,
  "layer_decomposition_options": {
    "max_images": 10,
    "text_recognition": true
  },
  "size": "1K"
}'
```

## 查询任务

通过[任务查询接口](https://docs.apimart.ai/cn/api-reference/tasks/status.md)查询。前 30 秒可每 3 秒查询一次，之后每 5–10 秒查询一次。图层拆分可能需要几分钟，服务端单次最多等待 13 分钟；保存 `task_id` 并持续查询终态，不要重复提交生成请求。

```bash theme={null}
curl --request GET \
  --url 'https://api.apimart.ai/v1/tasks/task_example_seedream55' \
  --header 'Authorization: Bearer <token>'
```

按统一任务接口读取 `data.status`：`pending` / `processing` 表示处理中，`completed` 表示成功，`failed` 时读取 `data.error.message`，失败费用自动退回。成功后从 `data.result.images[].url[]` 获取图片地址。

> [!WARNING]
>
> 结果图保存 **3 天**，请及时下载。任务记录也仅保留 3 天，之后无法通过 `task_id` 查询。
>
> `data.result.images[].expires_at` 当前返回“任务完成时间 + 24 小时”的 Unix 秒级时间戳，是早于实际删除时间的保守标注。不要用它计算实际保留期或删除倒计时。

## 图层结果与 OCR

以下为字段结构示意，并非实测任务记录。尺寸、坐标和文字均为示例；实际返回可能缺少元数据字段，请按可选字段处理。

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_example_seedream55",
    "status": "completed",
    "progress": 100,
    "completed": 1794302642,
    "result": {
      "images": [
        {
          "url": ["https://example.com/base.png", "https://example.com/title.png"],
          "sizes": ["840x1248", "1512x702"],
          "output_formats": ["png", "png"],
          "backgrounds": ["opaque", "transparent"],
          "expires_at": 1794389042,
          "layer_decomposition": true,
          "layers": [
            {
              "z_index": 0,
              "size": "840x1248",
              "output_format": "png",
              "background": "opaque"
            },
            {
              "z_index": 1,
              "size": "1512x702",
              "output_format": "png",
              "background": "transparent",
              "name": "Sale title",
              "description": "Printed sale title",
              "bounding_box": {
                "absolute": [84, 156, 756, 468],
                "normalized": [100, 125, 900, 375]
              },
              "text_recognition": {
                "text": "SUMMER SALE",
                "lines": [
                  {
                    "bounding_box": {
                      "absolute": [126, 156, 714, 468],
                      "normalized": [150, 125, 850, 375]
                    },
                    "runs": [
                      {
                        "text": "SUMMER SALE",
                        "style": {
                          "similar_font_family": "Arial",
                          "foreground_color": "#222222",
                          "bold": true,
                          "italic": false,
                          "underline": false,
                          "strikethrough": false,
                          "shadow": false,
                          "translucent": false
                        }
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  }
}
```

在每个 `data.result.images[]` 对象中，`url`、`sizes`、`output_formats`、`backgrounds`、`layers` 按下标对应；元数据数组长度与 `url` 不一致时可能不返回该字段，不要假定所有数组始终存在。

| 字段 | 说明 |
| - | - |
| `url[]` | 平台图片直链。图层模式下第 0 项是底图，其后是图层；建议及时下载保存。 |
| `sizes[]` / `output_formats[]` | 对应图片的实际尺寸和格式。 |
| `backgrounds[]` | 对应图片的实际背景：`opaque` / `transparent`；请求 `background: "auto"` 时也以实际返回为准。 |
| `expires_at` | 当前为任务完成时间 + 24 小时（86400 秒）的 Unix 时间戳，是保守标注，不代表图片实际删除时间；不要据此计算删除倒计时。 |
| `layer_decomposition` | 是否为图层拆分结果。 |
| `layers[i].z_index` | 叠放顺序，底图为 0，按从小到大的顺序叠放。 |
| `layers[i].background` | 底图为 `opaque`，拆出的图层为 `transparent`。 |
| `layers[i].name` / `description` | 可选的图层名称和描述。 |
| `layers[i].bounding_box` | `absolute` 为底图坐标系的 `[left, top, right, bottom]` 像素坐标；`normalized` 为同一个框归一化到 0–1000 的坐标。底图没有此字段。 |
| `layers[i].text_recognition` | 仅在开启 OCR 且识别到规整文字时可能出现；艺术字、手写字及非文字层不返回。 |

使用绝对坐标时：`x=left`、`y=top`、`w=right-left`、`h=bottom-top`。映射到 `W × H` 画布时，使用归一化坐标：

```text theme={null}
x = left / 1000 * W
y = top / 1000 * H
w = (right - left) / 1000 * W
h = (bottom - top) / 1000 * H
```

图层文件按所选档位独立输出，实际宽高可能不同于 `bounding_box` 的宽高。合成时，将图层缩放到边界框的 `w × h` 后放置在 `(x, y)`，不要直接用图层文件像素作为底图坐标。

### 文字识别字段

`text_recognition` 使用上游模型返回的 OCR 结构，平台原样透传 `text`、`lines`、`runs` 和 `style` 等字段。

| 字段 | 说明 |
| - | - |
| `text` | 整层纯文本，行之间用 `\n` 分隔。 |
| `lines[].bounding_box` | 该行在底图中的边界框，坐标规则同上。 |
| `lines[].runs[]` | 同一行中样式不同的文字片段；每项包含 `text` 与 `style`。 |
| `runs[].style.similar_font_family` | 识别到的相近字体名称；无法识别时为 `unknown`。 |
| `runs[].style.foreground_color` | 文字颜色，格式为 `#RRGGBB`。 |
| `runs[].style.bold` / `italic` / `underline` / `strikethrough` / `shadow` / `translucent` | 布尔样式标记，均为模型识别结果，可能存在偏差。 |

OCR 和字体信息可用于展示、复制或辅助编辑，不能保证与原图完全一致。没有 OCR 字段时仍可使用返回的图层图片。

## 计费

输出图片和输入参考图分别计费，**每张参考图均收费，没有首张免费**；图层拆分所用的 1 张输入图也计费。

* 输出图片逐张按实际总像素分档：不超过 **2,610,000** 像素为低档，超过为高档。`1K` / `1.5K` 对应低档，`2K` 对应高档；精确像素按宽 × 高判断。
* 图片生成预扣所选输出档位费用，加上参考图数量 × 输入图单价；省略 `size` 或使用 `auto` 时按 `2K` 预扣。
* 图层拆分预扣 `max_images` × 输出预扣档位单价，再加上 **1 张输入图费用**。`max_images` 默认 30，包含底图，实际输出可能更少。
* 图层预扣按生效的 `size`（未传时取 `resolution`）：`1K` / `1.5K` 为低档，`2K` / `auto` 为高档；两者均省略时按 `auto` 高档预扣。
* 完成后按实际输出张数、每张实际像素档位及输入图数量结算，多退少补。底图和每个图层各算一张，不能把所有图片直接按请求档位结算。失败任务全额退款。

具体单价以[模型定价](https://apimart.ai/pricing)为准。

## 常见参数错误

以下包含平台入口和上游的参数校验错误。提交失败时读取 `error.message`；异步任务失败时读取 `data.error.message`。

| 报错片段 | 处理方式 |
| - | - |
| `does not support optimize_prompt_options.mode=fast` | 平台入口同步返回 HTTP 400；仅可使用 `standard`，省略也会默认启用优化。 |
| `must be one of: standard` | 上游 HTTP 400：`disabled` / `none` / `off` 均不支持，无法关闭优化。 |
| `only supports background auto, transparent or opaque` | 使用 `auto`、`transparent` 或 `opaque`。 |
| `cannot combine background=transparent with output_format=jpeg` | 透明背景使用 `output_format: "png"`。 |
| `does not accept background when layer_decomposition=true` | 图层模式移除 `background`，包括 `auto`。 |
| `layer_decomposition_options requires layer_decomposition=true` | 仅在图层拆分模式发送该对象。 |
| `layer_decomposition_options.max_images must be within [2, 100]` | `max_images` 使用 2–100 的整数，包含底图。 |
| `invalid layer_decomposition_options` | 使用正确类型；`max_images` 不能是字符串或小数，`text_recognition` 应为布尔值。 |
| `with layer_decomposition=true requires exactly 1 input image` | 图层拆分必须恰好传入 1 张图片。 |
| `only supports size 1K, 1.5K, 2K or auto` | 图层模式按 `size` 优先、`resolution` 次之取值，仅允许 `1K` / `1.5K` / `2K` / `auto`；比例或像素写法同步返回 HTTP 400。 |
| `` `n` must be 1 `` | 将 `n` 设为 `1`，不支持组图。 |
| `does not support stream` / `does not support tools` | 移除 `sequential_image_generation`、`stream` 和 `tools`。 |
| `supports up to 10 reference images` | 参考图最多 10 张。 |
| `reference image too large for seedream-5-5` | 单张参考图不得超过 30 MiB 或 3600 万总像素；压缩或缩小图片后重试。 |
| `does not support size` / `requires total pixels` / `requires aspect ratio` | 检查总像素范围、宽高比和尺寸写法；不支持 3K / 4K。 |
| `` `prompt` parameter is required `` | 图片生成必须提供提示词；只有图层拆分可以省略。 |

## 任务失败原因

当 `data.status` 为 `failed` 时，读取 `data.error.message`，并结合 `data.error.reason` 处理；失败费用自动退回。未返回 `reason` 或值不在下表时，使用 `message` 作为兜底提示。

| `data.error.reason` | 处理方式 |
| - | - |
| `content_policy_violation` | 输入或输出未通过内容审核；修改提示词或图片后再提交。 |
| `invalid_parameter` / `unsupported_option` | 参数或组合不受支持；调整参数后再提交。 |
| `invalid_media` | 输入图片损坏或格式不支持；检查并转换图片。 |
| `media_unreachable` | 图片 URL 无法访问；检查公网访问权限或重新上传。 |
| `generation_timeout` | 生成超时；稍后重试。 |
| `service_unavailable` | 服务暂时繁忙；稍后重试。 |
| `delivery_failed` / `internal_error` / `unknown_error` | 交付或平台内部错误；根据返回说明稍后重试。 |


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