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

# Seedream API：图片生成与编辑

> 用老张API调用 Seedream 5.0 Flash、5.0 Pro、5.0、4.5 和 4.0：文生图，或传入 1–10 张参考图改图，附 cURL、Python、多参考图数组、透明图层拆分与结果保存示例。

Seedream 是字节跳动 BytePlus ModelArk 的图像模型，最新版本为 5.0 Flash 和 5.0 Pro。在老张API中，文生图和图改图用同一个 JSON 接口，按输出图片张数计费。除 5.0 Pro 从第 2 张参考图起每张另收 \$0.003 外，参考图不另收费。

| 项目 | 内容 |
| - | - |
| Seedream 5.0 Flash | `seedream-5-0-flash-260915`，\$0.018/张，出图快、Seedream 全系单价最低 |
| Seedream 5.0 Pro | `seedream-5-0-pro-260628`，\$0.12/张，第 2 张参考图起每张另收 \$0.003；画质最高、出图约 2 分钟 |
| Seedream 5.0 | `seedream-5-0-260128`，\$0.035/张 |
| Seedream 4.5 | `seedream-4-5-251128`，\$0.045/张 |
| Seedream 4.0 | `seedream-4-0-250828`，\$0.035/张 |
| 价格来源 | 2026 年 9 月 25 日公开价格配置，见[模型与价格总表](/models) |
| 接口 | `POST /v1/images/generations`，请求体为 JSON |
| 文生图与图改图 | 只传 `prompt` 是文生图，再加上 `image` 就是图改图 |
| 参考图 | `image` 可以是一张图片，也可以是最多 10 张图片组成的数组 |
| 令牌 | `default` 分组，计费模式为按量优先（推荐）或按次计费 |
| 分层（透明图层） | 5.0 Flash 和 5.0 Pro 支持，按输出张数计费，见下方「分层」一节 |

本页示例使用 Seedream 5.0，换用其他版本时只改 `model`。5.0 Flash 和 5.0 Pro 不支持 `sequential_image_generation` 和 `stream`，传入任何值都会返回 400，切换前先删掉这两个字段。

## 准备令牌与环境

在[令牌管理](https://api.laozhang.ai/token)新建 `default` 分组的令牌，计费模式选择「按量优先」（推荐）或「按次计费」，然后点击创建。按量优先的令牌同时可以调用按量计费的模型；按次计费的令牌只能调用按次计费的模型。

<img src="https://mintcdn.com/laozhangai-edd05f2c/_loZ0Jy0ZI__xJ9z/images/token-create-per-request.png?fit=max&auto=format&n=_loZ0Jy0ZI__xJ9z&q=85&s=1fdceb804bb3ad50f83a21ec65b4d807" alt="在令牌管理中新建令牌，计费模式选择按次计费后点击创建" width="1364" height="1170" data-path="images/token-create-per-request.png" />

设置密钥，并安装 Python 示例用到的依赖：

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
python -m pip install requests pillow
```

cURL 示例把响应写入 JSON 文件，再用 [Images API 参考中的保存脚本](/api-reference/images#保存返回图片) `save_images.py` 下载图片（脚本依赖 `pillow`）。Python 示例拿到 URL 后直接下载。返回的图片地址是临时链接，拿到后请尽快保存。

## 文生图

### cURL

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-260128",
    "prompt": "A beautiful sunset over mountains, realistic style",
    "size": "2K",
    "response_format": "url",
    "watermark": false
  }' \
  -o seedream-generation.json

python save_images.py seedream-generation.json seedream-generation
```

保存脚本会下载 `data[0].url` 指向的图片，并按实际格式命名，例如 `seedream-generation-1.jpg`。

### Python

```python theme={null}
import os
from pathlib import Path

import requests

API_URL = "https://api.laozhang.ai/v1/images/generations"
HEADERS = {"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"}

response = requests.post(
    API_URL,
    headers=HEADERS,
    json={
        "model": "seedream-5-0-260128",
        "prompt": "A beautiful sunset over mountains, realistic style",
        "size": "2K",
        "response_format": "url",
        "watermark": False,
    },
    timeout=120,
)
response.raise_for_status()
result = response.json()
if not result.get("data"):
    raise SystemExit(f"没有返回图片：{result}")

image = requests.get(result["data"][0]["url"], timeout=60)
image.raise_for_status()
Path("seedream-generation.jpg").write_bytes(image.content)
print("已保存 seedream-generation.jpg")
```

## 图改图

在请求中加入 `image` 即为图改图。参考图可以是公网 URL，也可以是 `data:image/png;base64,...` 形式的 Base64 data URL。提示词里写清楚要改变什么、保留什么。

### 单张参考图

下面的示例使用 BytePlus 文档中的公开示例图，可以直接运行：

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-260128",
    "prompt": "Generate a close-up image of a dog lying on lush grass.",
    "image": "https://ark-doc.tos-ap-southeast-1.bytepluses.com/doc_image/seedream4_imageToimage.png",
    "size": "2K",
    "response_format": "url",
    "watermark": false
  }' \
  -o seedream-edit.json

python save_images.py seedream-edit.json seedream-edit
```

### 多张参考图

`image` 传数组，最多 10 张。数组顺序就是提示词里的图 1、图 2、图 3……下面把两张本地图片转成 data URL 后发送：

```bash theme={null}
IMG1=$(base64 < model.png | tr -d '\n')
IMG2=$(base64 < jacket.png | tr -d '\n')

curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- \
  -o seedream-multi-edit.json <<EOF
{
  "model": "seedream-5-0-260128",
  "prompt": "让图 1 中的模特穿上图 2 的外套，保持图 1 的姿势、表情和背景不变",
  "image": [
    "data:image/png;base64,$IMG1",
    "data:image/png;base64,$IMG2"
  ],
  "size": "2K",
  "response_format": "url",
  "watermark": false
}
EOF

python save_images.py seedream-multi-edit.json seedream-multi-edit
```

### Python：本地文件或 URL

```python theme={null}
import base64
import mimetypes
import os
from pathlib import Path

import requests

API_URL = "https://api.laozhang.ai/v1/images/generations"
HEADERS = {"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"}


def to_reference(source):
    """公网 URL 原样使用，本地文件转成 data URL。"""
    if source.startswith(("http://", "https://", "data:")):
        return source
    path = Path(source)
    mime_type = mimetypes.guess_type(path.name)[0] or "image/png"
    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
    return f"data:{mime_type};base64,{encoded}"


def seedream_edit(prompt, images, output_prefix, model="seedream-5-0-260128"):
    if not 1 <= len(images) <= 10:
        raise ValueError("Seedream 图改图需要 1–10 张参考图")
    references = [to_reference(source) for source in images]
    response = requests.post(
        API_URL,
        headers=HEADERS,
        json={
            "model": model,
            "prompt": prompt,
            # 一张参考图直接传字符串，多张传数组
            "image": references[0] if len(references) == 1 else references,
            "size": "2K",
            "response_format": "url",
            "watermark": False,
        },
        timeout=180,
    )
    response.raise_for_status()
    result = response.json()
    if not result.get("data"):
        raise SystemExit(f"没有返回图片：{result}")

    # 逐张保存 data[] 中的全部图片（组图模式可能返回多张）
    for index, item in enumerate(result["data"], start=1):
        image = requests.get(item["url"], timeout=60)
        image.raise_for_status()
        output = Path(f"{output_prefix}-{index}.jpg")
        output.write_bytes(image.content)
        print(f"已保存 {output}")


seedream_edit(
    prompt="让图 1 中的模特穿上图 2 的外套，保持图 1 的姿势、表情和背景不变",
    images=["model.png", "jacket.png"],
    output_prefix="seedream-multi-edit",
)
```

## 分层：拆出透明图层

`seedream-5-0-flash-260915` 和 `seedream-5-0-pro-260628` 都能把一张成品图拆成一张补全后的背景底图和若干张透明 PNG 图层，每个图层只含一个元素，适合换背景、二次排版和素材复用。只在提示词里要求「透明背景」得不到 alpha 通道，需要透明素材时用分层。

两款模型都按输出张数计费，Pro 每张的价格约是 Flash 的 6.7 倍，分层默认用 Flash 即可。

分层请求与普通改图的区别：

* 设置 `"layer_decomposition": true`。
* `image` 只传 1 张图片，写成字符串或只含一项的数组都可以。
* `prompt` 可以不传，也可以传空字符串，模型会自动识别画面里的主要元素。
* `size` 推荐用 `1K`，不能写像素宽高。
* 分层可用的尺寸档位只有 `1K`、`1.5K`、`2K`、`auto`。
* 只有 5.0 Flash 和 5.0 Pro 支持分层。`seedream-5-0-260128` 和 `seedream-4-5-251128` 收到该参数会返回 400，错误码为 `InvalidParameter`。

### 发送分层请求

```bash theme={null}
curl --fail-with-body --max-time 360 "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-flash-260915",
    "image": "https://example.com/your-poster.jpg",
    "layer_decomposition": true,
    "size": "1K",
    "response_format": "url",
    "watermark": false
  }' \
  -o seedream-layers.json
```

把 `image` 换成你自己可公网下载的图片，或者 Base64 data URL。换成 Pro 时只改 `model`。

<Warning>
  **分层按输出张数计费：Flash 每张 \$0.018，Pro 每张 \$0.12。**

  * 图层数量由画面内容决定，无法事先指定，同一张图两次分层的张数也可能不同。例如一张电影海报拆出 6 张（1 张底图 + 5 个图层），Flash 计 \$0.108，Pro 计 \$0.72；元素多的画面可能返回十几张，Flash 返回 16 张计 \$0.288。
  * 用 `1K` 拆出 6 张时，Flash 不到 1 分钟、Pro 约 70 秒返回，图层越多越慢。客户端超时设到 300 秒以上；2K 分层耗时可能很长，客户端提前断开后请求仍会计费。
  * 图片无法分层时返回 400，不计费。
  * 底图里被移走元素的位置是模型补画的内容，商用前请人工检查。
</Warning>

### 分层响应

`data[]` 的第 1 项是底图，其余每项是一个图层。下面的响应只保留了底图和其中一个图层：

```json theme={null}
{
  "data": [
    {
      "url": "https://example.com/base.jpeg",
      "size": "896x1200",
      "output_format": "jpeg",
      "z_index": 0
    },
    {
      "url": "https://example.com/layer.png",
      "size": "916x529",
      "output_format": "png",
      "z_index": 4,
      "bounding_box": {
        "absolute": [260, 716, 619, 924],
        "normalized": [290, 597, 690, 769]
      },
      "name": "Spaceship",
      "description": "Sci-fi spaceship with blue engine glow effects, separate from the background nebula."
    }
  ],
  "usage": {
    "input_images": 1,
    "generated_images": 6
  }
}
```

| 字段 | 说明 |
| - | - |
| `url` | 临时下载链接，拿到后尽快保存。链接不带跨域响应头，浏览器前端直接调用时改用 `"response_format": "b64_json"`，图片数据会以 `b64_json` 字段返回 |
| `size` | 这张图片本身的像素宽高 |
| `output_format` | 底图跟随请求的 `output_format`，默认 `jpeg`；图层固定为 RGBA 的 `png` |
| `z_index` | 叠放顺序：底图为 0，图层从 1 起递增，数值越大越靠上 |
| `bounding_box.absolute` | 图层在底图上的位置 `[左, 上, 右, 下]`，单位是底图像素 |
| `bounding_box.normalized` | 同一个框换算到 0–1000 的坐标 |
| `name`、`description` | 模型为图层生成的英文名称和说明，底图没有 |
| `usage.generated_images` | 本次返回的图片张数，包括底图 |

`usage` 里还有 `output_tokens`，但费用只按图片张数计算。

图层 PNG 的像素尺寸不一定等于 `bounding_box` 的大小，例如上面的图层是 916×529，而框只有 359×208。重新合成时要把图层缩放到 `absolute` 框里，不能按原尺寸直接贴。

### 保存图层并重新合成

下面的脚本读取上一步保存的 `seedream-layers.json`，把每张图片按 `z_index` 和图层名称保存，再用 Pillow 按 `bounding_box.absolute` 叠回底图，得到 `recomposited.png`：

```python save_layers.py theme={null}
import json
import re
import sys
import urllib.request
from io import BytesIO
from pathlib import Path

from PIL import Image

response = json.loads(Path(sys.argv[1]).read_text())
canvas = None

# 按 z_index 从小到大处理：先底图，再逐层往上叠
for item in sorted(response["data"], key=lambda item: item["z_index"]):
    with urllib.request.urlopen(item["url"], timeout=120) as download:
        content = download.read()
    name = re.sub(r"[^a-z0-9]+", "-", item.get("name", "base").lower()).strip("-")
    extension = "png" if item["output_format"] == "png" else "jpg"
    path = Path(f"layer-{item['z_index']:02d}-{name or 'layer'}.{extension}")
    path.write_bytes(content)
    print(f"已保存 {path}")

    image = Image.open(BytesIO(content)).convert("RGBA")
    if "bounding_box" not in item:
        canvas = image  # 底图没有 bounding_box
        continue
    left, top, right, bottom = item["bounding_box"]["absolute"]
    layer = image.resize((right - left, bottom - top), Image.LANCZOS)
    canvas.alpha_composite(layer, (left, top))

canvas.save("recomposited.png")
print("已保存 recomposited.png")
```

```bash theme={null}
python save_layers.py seedream-layers.json
```

运行后会得到 `layer-00-base.jpg`、`layer-04-spaceship.png` 这样的文件。想换背景或删掉某个元素时，替换底图或跳过对应图层再合成即可。

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | `seedream-5-0-flash-260915`、`seedream-5-0-pro-260628`、`seedream-5-0-260128`、`seedream-4-5-251128` 或 `seedream-4-0-250828` |
| `prompt` | string | 是 | 图片描述或编辑指令；分层时可以不传 |
| `image` | string 或 string\[] | 否 | 参考图，公网 URL 或 Base64 data URL；数组最多 10 张，分层时只能 1 张。传入即为图改图 |
| `size` | string | 否 | 输出尺寸，示例使用 `2K`；也可以写像素宽高，各模型的范围见[常见问题](#常见问题) |
| `response_format` | string | 否 | `url`（默认）或 `b64_json` |
| `output_format` | string | 否 | 5.0 Flash、5.0 Pro 和 5.0 可选 `png` 或 `jpeg`；分层时只决定底图格式 |
| `watermark` | boolean | 否 | 是否添加水印，示例设为 `false` |
| `sequential_image_generation` | string | 否 | `disabled`（默认）每次生成一张；`auto` 为组图模式，由模型按提示词决定返回几张，见[常见问题](#常见问题)。5.0 Flash 和 5.0 Pro 不支持，不要传 |
| `layer_decomposition` | boolean | 否 | 5.0 Flash 和 5.0 Pro 可用：设为 `true` 并传 1 张参考图，返回背景底图和透明图层，见上方「分层」一节 |

组图模式和分层一次可能返回多张图片，要逐项保存 `data[]`：`save_images.py`、上面的 `seedream_edit()` 和 `save_layers.py` 都会保存全部图片。

普通生成和改图的成功响应格式如下，分层响应的字段见上方「分层响应」：

```json theme={null}
{
  "created": 1726051200,
  "data": [
    {
      "url": "https://example.com/generated_image.jpg",
      "revised_prompt": "..."
    }
  ]
}
```

没有 `data` 时，响应里会有错误信息。检查模型 ID、参考图地址和令牌分组，并在[调用日志](/faq/call-logs)中核对请求记录和扣费。

## 常见问题

### 新接入选哪个版本？

按任务选：

| 需求 | 模型 | 单价 |
| - | - | - |
| 批量出图、海报与带文字的设计图、控制成本 | `seedream-5-0-flash-260915`（5.0 Flash） | \$0.018/张 |
| 写实人像、材质细节、复杂指令，对画质要求最高 | `seedream-5-0-pro-260628`（5.0 Pro） | \$0.12/张 |
| 需要 3K、组图模式或流式输出 | `seedream-5-0-260128`（5.0） | \$0.035/张 |
| 需要 4K | `seedream-4-5-251128`（4.5）或 `seedream-4-0-250828`（4.0） | \$0.045/张、\$0.035/张 |
| 把成品图拆成透明图层 | `seedream-5-0-flash-260915`（Pro 也支持，但每张贵约 6.7 倍） | \$0.018/张 |

5.0 Flash 通常 20 秒以内出图；5.0 Pro 常见约 2 分钟，客户端超时要设到 240 秒以上。`seedream-5-0-260128` 在 BytePlus 文档中对应 Seedream 5.0 lite。两款新模型的上线说明见 [Seedream 5.0 Flash 与 5.0 Pro 上线公告](/announcements/seedream-5-0-flash-pro-2026-09)。

### `size` 可以填哪些值？能出 4K 吗？

`size` 有两种写法，二选一：写分辨率档位，并在提示词里描述比例（例如「16:9 横版」）；或者直接写像素宽高，例如 `2848x1600`。各模型可用的分辨率档位：

* `seedream-5-0-flash-260915`：`1K`、`1.5K`、`2K`，默认 2K
* `seedream-5-0-pro-260628`：`1K`、`2K`
* `seedream-5-0-260128`：`2K`、`3K`（最高 3K）
* `seedream-4-5-251128`：`2K`、`4K`
* `seedream-4-0-250828`：`1K`、`2K`、`4K`

写像素宽高时，宽高比都要在 1/16 到 16 之间，总像素要在对应模型的范围内：

| 模型 | 总像素下限 | 总像素上限 |
| - | - | - |
| 5.0 Flash | 921,600（1280×720） | 4,624,220 |
| 5.0 Pro | 未公布 | 约 419 万，例如 `2048x2048`、`2720x1530` |
| 5.0 | 3,686,400（2560×1440） | 3K 档 |
| 4.5 | 3,686,400（2560×1440） | 4096×4096 |
| 4.0 | 921,600（1280×720） | 4096×4096 |

所以 `1024x1024` 这类小尺寸在 5.0 和 4.5 上会报错。每张图片的单价不随尺寸变化。

5.0 Flash 和 5.0 Pro 用预设档位时，画面宽高比由模型按内容决定，提示词里写比例不一定生效；需要固定比例时直接写像素宽高。

分层请求只接受 `1K`、`1.5K`、`2K`、`auto` 档位，不能写像素宽高。

### 组图模式怎么用？怎么计费？

组图模式只适用于 5.0、4.5 和 4.0；5.0 Flash 和 5.0 Pro 不支持，传入会返回 400。

把 `sequential_image_generation` 设为 `auto`，模型会按提示词决定返回几张相关的图片，例如「生成同一角色在早、中、晚的三张图」。

需要限制张数时，按 BytePlus 文档传 `sequential_image_generation_options.max_images`（1–15）。参考图数量加上生成张数不能超过 15。

组图响应的 `data[]` 里有多张图片，要逐项保存。费用按实际返回的图片张数计算，例如用 `seedream-5-0-260128` 返回 4 张计 \$0.14；参考图不另外收费。实际扣费以[调用日志](/faq/call-logs)为准。

### 本地图片怎么传？参考图有什么限制？

把图片转成 data URL 放进 `image`，写法是 `data:image/png;base64,<Base64 编码>`，其中格式名必须小写，如 `png`、`jpeg`。多张参考图的写法见[多张参考图](#多张参考图)。

BytePlus 对每张参考图的要求：

* 格式为 jpeg、png、webp、bmp、tiff、gif、heic 或 heif；
* 单张不超过 30 MB；
* 宽和高都大于 14 像素，总像素不超过 6000×6000；
* 宽高比在 1/16 到 16 之间。

公网 URL 必须能被直接下载。图片较大时优先用公网 URL，因为 Base64 编码会让请求体增大约三分之一。

### 怎样去掉水印？

在请求里传 `"watermark": false`，本页示例都已这样设置。BytePlus 的 `watermark` 默认为 `true`，会在图片右下角加「AI generated」字样，所以需要无水印图片时要显式传 `false`。

### 结果链接保存多久？能返回 Base64 吗？

BytePlus 官方说明图片 URL 在生成后 24 小时内有效。收到响应后尽快下载到自己的存储，不要把返回的链接当作长期地址。

需要图片内容直接随响应返回时，把 `response_format` 设为 `b64_json`。[Images API 参考中的保存脚本](/api-reference/images#保存返回图片)同时支持 `url` 和 `b64_json` 两种返回。

### 请求失败会扣费吗？

一般不会。参数错误、内容审核拦截等直接返回错误、没有生成图片的请求不计费，成功返回图片才计费。

客户端超时不等于请求失败：服务端可能已经生成完成并扣费。5.0 Pro 常见约 2 分钟出图，分层也可能超过 1 分钟，请把超时留足。重新提交前先到[调用日志](/faq/call-logs)确认该请求的状态，避免重复扣费。实际扣费以调用日志为准。

## 相关文档与来源

* [BytePlus ModelArk 图像生成 API](https://docs.byteplus.com/en/docs/ModelArk/1541523)：官方参数说明、`size` 取值范围与结果链接有效期
* [BytePlus 图像生成教程](https://docs.byteplus.com/en/docs/ModelArk/1824121)：各版本能力对比、组图用法与参考图限制
* [图像生成 API 选型与价格](/api-capabilities/image-generation-guide)：与其他图像模型对比
* [FLUX.2 API](/api-capabilities/flux-image-generation)：另一款支持多张参考图的模型
* [控制台模型价格](https://api.laozhang.ai/account/pricing)：当前单价与可用分组


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