seedream-image

Seedream 图像

使用 POST https://api.acedata.cloud/seedream/images。通过 Authorization: Bearer $ACEDATACLOUD_API_TOKEN 进行身份验证，并使用 JSON 请求正文。

首次设置

1. 使用 clawhub install @acedatacloud/seedream 安装官方 Skill。确认 ClawHub 发布者是 @acedatacloud。
2. 登录 AceDataCloud → Applications，打开 General application，检查 Seedream 访问权限、余额和当前定价。复制其 API 密钥，或选择 Manage Keys → Create 创建单独的密钥。复制密钥值，不要包含 Bearer ；platform-... 管理令牌不是服务 API 密钥。
3. 如果启用了 Allowed APIs 限制，请加入 /seedream/images 和 /seedream/tasks。以下高级工作流可能会调用其他路由。
4. 在 OpenClaw Gateway 主机上，将 ACEDATACLOUD_API_TOKEN=your_api_key_here 写入 ~/.openclaw/.env，然后重启 Gateway 并开始新会话。如需直接在终端中测试，请在该 shell 中运行 export ACEDATACLOUD_API_TOKEN="your_api_key_here"。切勿将密钥放入提示词或提交 .env 文件。
5. 按照下方的 生成或编辑 示例操作。如果此工作流返回任务 ID，请查询同一任务直至完成；不要仅为查看进度而再次提交相同的计费请求。

密钥设置、首次运行和故障排除图解 · 令牌详情

根据所需能力选择模型

能力	Seedream 5.0 Pro	Seedream 5.0 Lite
模型 ID	doubao-seedream-5-0-pro-260628	doubao-seedream-5-0-lite-260128
生成/编辑单张图像	是	是
参考图像	最多 10 张	最多 14 张
关联图像集	否	是；输入 + 输出 ≤ 15 张
流式传输 / 网络搜索	否	是
图层分解 / 透明背景	是	否
提示词优化	standard、fast	standard
预设尺寸	1K、1.5K、2K	2K、3K、4K

Seedream 4.5 和 4.0 仍可用于兼容性支持。不要向不支持某参数的模型发送该参数。

生成或编辑

curl https://api.acedata.cloud/seedream/images \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-lite-260128",
    "prompt": "a four-panel storyboard of a courier crossing a rainy neon city",
    "size": "2K",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {"max_images": 4},
    "watermark": false
  }'

编辑时，添加 image，其值可以是一个 URL/Base64 字符串或数组。response_format 可设为 url 或 b64_json；5.0 Pro/Lite 还支持将 output_format 设为 jpeg 或 png。显式指定尺寸时，使用 WIDTHxHEIGHT 格式，并须满足所选模型的像素和宽高比限制。

仅在需要当前信息时使用 Lite 网络搜索：

{"tools": [{"type": "web_search"}]}

使用 Pro 编辑透明背景图像

使用一张透明 PNG 输入图像，并指定 PNG 输出：

{
  "model": "doubao-seedream-5-0-pro-260628",
  "prompt": "replace the parrot with a peacock",
  "image": "https://example.com/layer.png",
  "background": "transparent",
  "output_format": "png",
  "size": "1.5K"
}

不要将 background 与图层分解结合使用。transparent 与 JPEG 搭配无效。

将图像分解为可编辑图层

layer_decomposition 仅适用于 Pro，且必须提供一张 PNG/JPEG。省略 prompt 可自动分解；也可以用自然语言描述所需元素，或使用归一化的 <bbox> 坐标。

curl https://api.acedata.cloud/seedream/images \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "image": "https://example.com/poster.png",
    "layer_decomposition": true,
    "size": "auto",
    "watermark": false
  }'

响应包含一张基础图像（z_index: 0）和最多 16 个透明 PNG 图层。每个图层都可以包含 name、description 和 bounding_box.absolute/normalized。如需重新合成，请将每个图层缩放至其边界框的宽度和高度，放置在 left/top 位置，并按 z_index 升序绘制。任何图层失败都会导致整个分解失败。

异步任务

生成可能需要一些时间。建议使用 "async": true；响应会返回 task_id。使用以下方式轮询：

POST /seedream/tasks
{"action": "retrieve", "id": "<task_id>"}

请参阅异步任务轮询。仅在存在真实公共 Webhook 时使用 callback_url。不要使用健康检查端点来伪造回调。

流式处理

Lite/4.x 支持流式处理。发送 "stream": true 并设置 Accept: application/x-ndjson；逐行读取标准化的 JSON 事件，直到收到 image_generation.completed。不要将流式处理与 async 或 callback_url 结合使用。

• image_generation.partial_succeeded：一张已生成的图像
• image_generation.partial_failed：一个失败的项目；其他 Lite 图像仍可能成功
• image_generation.completed：最终用量，也是唯一的计费完成事件

Agent 工具

• MCP：pip install mcp-seedream-pro；使用 seedream_generate_image、seedream_edit_image、seedream_decompose_image，然后使用 seedream_get_task 轮询。
• CLI：pip install seedream-cli；使用 seedream generate、seedream edit、seedream decompose 或 seedream generate --stream --json。
• 托管 MCP：https://seedream.mcp.acedata.cloud/mcp。

MCP 图像工具是异步的，因此实时流式处理请使用 REST 或 CLI。

结果与计费保障

• URL 结果会过期；请及时保存文件。
• Lite 的 data[] 可能混合成功图像和逐项 error 对象。只统计成功的图像。
• Pro 的图层项目按实际输出大小单独计费；底图和每个成功图层分别计费。
• 请保留 z_index、边界框、项目错误、tools 和 usage；不要将响应简化为 URL 列表。
• 切勿仅根据请求的尺寸估算最终费用。请使用返回的 cost/用量和实时定价页面：https://platform.acedata.cloud/services/seedream?tab=pricing。