Seedream 5.5 API 教程：Python 代码、价格与实际输出

调用 Seedream 5.5 API 的方法是：向 https://api.seedrouter.ai/v1/images/generations 发送 POST 请求，带上 "model": "seedream-5-5" 和提示词，保存返回的任务 id，然后轮询 GET /v1/tasks/{id}，直到状态变为 completed。 完成的任务里包含图像 URL。同一个请求也支持使用最多 10 张参考图编辑、生成透明背景的 PNG，以及将一张图像分解为透明图层。

ByteDance 于 2026 年 11 月 9 日发布 Seedream 5.5，主要带来三项变化：更稳定的多轮编辑、原生透明输出，以及更真实的图像和更清晰的小字。^[1] 第二天，我们在 SeedRouter 上运行了三次。本教程就用这三次实测，展示发送的代码、返回的结果、耗时和费用。所有字段见 Seedream 5.5 API 文档，Playground 在模型页面。

第一次调用 Seedream 5.5 API 前需要准备什么？

两样东西：一个 API Key 和模型 ID。无需下载任何模型文件。ByteDance 尚未发布 Seedream 5.5 的权重，因此模型通过托管 API 运行，你的代码只需发送 JSON。

在 API Key 页面创建 Key，并把它保存在服务端的环境变量中，绝不要放进浏览器端代码：

export SEEDROUTER_API_KEY="your-key"
pip install requests

模型 ID 为 seedream-5-5。文生图、编辑和图层分解都用这一个 ID，由请求字段决定执行哪种操作。新账户有少量免费余额，足够先测试几张 1K 图像，再决定是否充值。

如何用 Python 生成图像？

提交后立即返回的是任务，而非图像。这个脚本提交提示词，每隔 10 秒轮询一次，15 分钟后停止等待，并保存返回的每张图像。

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}


def submit(body):
    r = requests.post(f"{API}/images/generations", headers=HEADERS, json=body, timeout=60)
    r.raise_for_status()
    return r.json()["id"]


def wait(task_id, limit=900):
    deadline = time.time() + limit
    while time.time() < deadline:
        r = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        task = r.json()
        if task["status"] in ("completed", "failed"):
            return task
        time.sleep(10)
    raise TimeoutError(f"{task_id} is still running; poll it again later")


task_id = submit({
    "model": "seedream-5-5",
    "prompt": "A ceramic teapot shaped like a sleeping fox on a linen tablecloth, "
              "soft morning window light, shallow depth of field. No text.",
    "size": "1K",
})
task = wait(task_id)
if task["status"] == "failed":
    raise RuntimeError(task["error"]["message"])

for i, image in enumerate(task["output"]["data"]):
    data = requests.get(image["url"], timeout=60).content
    with open(f"seedream-{i}.{image['output_format']}", "wb") as f:
        f.write(data)
    print(image["size"], image["url"])

这就是我们的第一次测试。耗时 47 秒，返回一张 1248 × 832 的 PNG。

这个循环中的两个习惯对生产使用很重要。轮询超时后，保留任务 ID 并继续查询，图像可能仍在生成中。不要再次发送请求来“重试”，因为这会创建第二个任务，并再次收费。

哪些请求字段需要关注？

大多数请求只需 model、prompt 和 size。最常设置的字段及其默认值如下：

最大输出为 2K。我们的 2K、16:9 编辑返回了 2560 × 1440，精确像素尺寸的总像素最高可达 4,624,220。没有宽高比字段：要固定画面形状，请传入精确像素尺寸。没有 3K 或 4K 档位，如果需要更大的文件，必须在后期放大。API 文档列出了所有字段。文档未列出的字段会被丢弃，而非导致请求被拒绝，因此误带其他图像 API 的 seed、style 或 n 不会让请求失败，也不会产生任何效果。一次请求生成一张图像。

如何用参考图编辑图像？

将原图放入 image，在提示词中说明要修改和保留的内容。我们的第二次测试，将晴天里一位油漆工站在灯塔环廊上的照片改成了冬夜：

task_id = submit({
    "model": "seedream-5-5",
    "prompt": "Turn this scene into a snowy winter night with warm light from "
              "the lighthouse windows, keep the composition",
    "image": "https://static.seedrouter.ai/media/landing/models/seedream-5-5/v1/lighthouse-source.webp",
    "size": "2560x1440",
})

耗时 40 秒，返回一张 2560 × 1440 的 PNG。油漆工、他的姿势、刷子、盘起的绳索、两个油漆桶和栏杆都留在原位。画面增加了飘雪、平台与肩膀上的积雪、暗色天空，以及塔身红色条带上方亮起的窗户。

使用多张参考图时，按它们在列表中的顺序指代（例如“图 2 中的夹克”）。每张参考图均计费，第一张也收费，因此只发送编辑需要的图像。

ByteDance 对此版本的主要说明是：在多轮编辑中，未编辑区域能在像素级保持一致，并经过连续 100 轮的测试。^[1] 通过 API 进行多轮编辑就是一个循环：取出已完成任务中的 URL，作为下一次请求的 image 传入。我们还没亲自测试过这么长的连续编辑，因此无法确认 100 轮这一数字。请注意，每一轮都是一个新任务，都会收取参考图费用。

如何生成透明 PNG？

将 background 设为 transparent，并保持 output_format 为 png。可以仅使用提示词，也可以提供参考图：

task_id = submit({
    "model": "seedream-5-5",
    "prompt": "A glossy red enamel pin shaped like a cherry, product cutout",
    "background": "transparent",
    "size": "1K",
})

transparent 与 jpeg 的组合会在任务创建前被拒绝，因为 JPEG 没有 alpha 通道。ByteDance 将这项能力描述为原生 RGBA 输出，支持全透明和半透明，并精细渲染边缘，因此素材无需另外去除背景。^[1]

如何通过 API 将图像分解为图层？

传入且仅传入一张图像，并设置 layer_decomposition: true。我们的第三次测试开启文字识别，将一张爵士乐海报分解为最多四张图像：

task_id = submit({
    "model": "seedream-5-5",
    "image": "https://static.seedrouter.ai/media/landing/models/seedream-5-5/v1/poster-source.webp",
    "layer_decomposition": True,
    "size": "1K",
    "layer_decomposition_options": {"max_images": 4, "text_recognition": True},
})

耗时 39 秒，返回四张图像：底图和三个透明图层。

两个文字图层都附带了识别出的文字。标题图层的 text_recognition 包含 "BLUE TIDE\nSESSIONS"，字体推测为 HTF Didot，颜色为 #122C4D；活动信息图层则包含 "LIVE JAZZ · PIER 7 HALL · SATURDAY 9 PM"。每行均有自己的边界框和样式，因此你可以用自己的字体在相同位置重新输入文字。

使用结果前，有三点需要了解：

• 图层文件尺寸大于边界框。 每层的放大倍数不同：标题为 1.74×，插画为 1.08×，活动信息为 2.59×。放置前先将每张 PNG 缩放到 bounding_box.absolute 对应的尺寸，再按 z_index 升序叠加图层。
• max_images 是数量上限，上限过低会合并元素。 只有四张图像的名额时，模型将萨克斯演奏者、海浪和珊瑚色太阳放进了同一图层。请为预期的元素数量留出空间。
• 同一个元素可能出现两次。 珊瑚色太阳既在插画图层里，也留在底图上。移动图层前请先检查底图。

Seedream 5.5 API 怎么收费？

按每张图像各自的尺寸计费，每张参考图另行收费。不超过 261 万像素的图像（1K 和 1.5K）属于低价档；2K 及更大尺寸属于高价档。图层分解按底图和每个图层各自的尺寸计费。失败的任务不收费。

我们在 2026 年 11 月 10 日进行了三次测试，各次的计费项目如下：

将这些数量乘以上表对应的价格，就能算出费用。图层分解尤其需要留意：这次按四张图像收费，而非一张，因为底图和每个图层均计费。

图层分解运行期间预留的余额会高于实际费用。任务受理时，会预留 max_images 张图像所需的余额，省略时按 30 张计算，auto 按高价档计算。任务完成后，按实际返回的图像扣费，并释放剩余金额。因此，不传 max_images 和 size 的分解请求，即使只返回四张图像，也需要有足够支付 30 张高价档图像加一张输入图像的余额才能启动。像我们的第三次测试（请求四张，返回四张）一样，将 max_images 设置为接近预期元素数量的值并选择档位，预留金额就会与账单金额相近。

需要处理哪些错误？

参考图必须是公开的 HTTP(S) URL。不接受 Base64 data URI，因此请先将文件上传到自己的存储空间。支持 JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC 和 HEIF，每张不超过 30 MB。完整错误码列表见错误码目录。

常见问题

有 Seedream 5.5 Pro 吗？

目前还没有。ByteDance 的发布文章写道："A Pro version of the Seedream 5.5 series will follow"（该系列之后会推出 Pro 版本），但未给出日期。^[1] 目前 API 只有一个模型，即 seedream-5-5。上一代的 Pro 模型仍以 Seedream 5.0 Pro 提供。

Seedream 5.5 API 免费吗？

不免费。它从预付余额中按张扣费，无需订阅。新账户的少量免费余额足够生成几张 1K 图像，你可以先运行上面的脚本，再决定是否充值。

可以下载 Seedream 5.5 吗？

不可以。ByteDance 尚未发布模型权重，因此没有可在本地运行的模型文件。你需要通过这样的 API 使用它。

最多能发送几张参考图？

image 最多接受 10 张。图层分解仅接受一张。

一次请求需要多久？

我们的三次测试耗时为 39 至 47 秒。返回许多图层的分解可能需要几分钟，因此上面的脚本最多轮询 15 分钟。

参考资料

1. ByteDance Seed。More Realistic Images, More Stable Editing Across 100 Rounds | Introducing Seedream 5.5。2026 年 11 月 9 日发布。于 2026 年 11 月 11 日查阅 seed.bytedance.com。
2. SeedRouter。Seedream 5.5 API 文档。/docs/seedream-5-5。