Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

4.9 KB
Raw Blame

Seedream 图像生成(@adelie/use-seedream)

一句话:把提示词交给火山方舟的豆包 Seedream,拿回图片,落在工作区里。

运行时就一个零依赖的 Node 文件(skills/seedream/kit/seedream.mjs)。它替 Agent 走完图片生成 的同步一步——一次请求,答案里直接带回图片:

POST /images/generations   一次请求 → data[] 里是图片:url(默认)或 b64_json
下载 url 或解码 b64_json    → 先写临时文件,写完了才改名

端点默认 https://ark.cn-beijing.volces.com/api/v3,鉴权是 Authorization: Bearer $ARK_API_KEY; 密钥只从环境读(Agent 的密钥库注入),脚本不写盘,也不留下别的痕迹。

用

node skills/seedream/kit/seedream.mjs --prompt "一只猫在窗台上晒太阳" --out cat.png

stderr 是给人看的进度行,stdout 只有一行 JSON,路径、耗时、用量都在里面:

{"ok":true,"model":"doubao-seedream-5-0-pro-260628","size":"2K","request_id":"0217…","elapsed_ms":18342,"paths":["/abs/cat.png"],"usage":{"generated_images":1}}

参数:--out(单图是文件路径,出多图时是目录;默认单图 ./seedream-<时间戳>.<格式>、 多图 ./seedream-<时间戳>/)、 --model(默认 doubao-seedream-5-0-pro-260628)、--image(参考图,可重复,最多 14 张, 本机文件会内联成 data:<mime>;base64,…)、--size(1K/2K/4K 或 2048x2048, 总像素须在 1280×720 与 4096×4096 之间)、--count(一次出组图,1–15 张)、--layers(图层拆分)、 --transparent、--format(png/jpeg;不传时按 --out 的扩展名定,两者都没有就是 png —— 一个叫 cat.png 的文件里装着 JPEG 字节,在很多看图工具里就是「坏文件」)、--seed、--watermark。 没传的参数不发给服务,所以模型自己的默认值说了算;未知参数直接报错,不会悄悄忽略。

出多图(--count 或 --layers)时 --out 当目录用,文件名是三位序号加内容: 001-base.png、002-z1-背景.png……序号后面带 -z<z_index>(有的话)和层名 —— 层名原样保留, 只把路径里放不下的字符(/ \ : * ? " < > |、空白、控制字符)换成 -,中文不会被打掉;服务没给名字时 用 base / layer。图层一律是 PNG。

退出码把结果分了类:0 成功;2 命令行不对;3 缺 ARK_API_KEY;4 接口拒了请求(upstream 里是服务原话);7 图片没下下来(临时文件已删,最终路径上不会留半张图)。

文件

路径 是什么
skills/seedream/kit/seedream.mjs 全部运行时:参数、请求、下载/解码、一行 JSON
skills/seedream/SKILL.md Agent 读的说明书:什么时候用、参数、错误码怎么处理、产物怎么给用户看
test/seedream.test.mjs 自检,桩服务冒充方舟,不用密钥也不花钱
plugin.json / package.json / icon.svg / LICENSE 插件清单、包信息、图标、Apache-2.0

测试

node --test "plugins/use-seedream/test/*.test.mjs"   # 或在包目录里 pnpm test

桩(test/ 里那个 http.createServer)冒充方舟:生成接口按用例返回 URL 或 base64, 图片地址由同一个桩提供,于是整条路——请求 → 下载 → 改名——都在本机跑完,并断言密钥只发往接口、 不发给图片 URL(真实的返回是签名链接)。它验的是脚本自己的行为;真实响应形状另外对着方舟真接口核过一次 (2026-10-28,doubao-seedream-5-0-pro-260628:出图、组图与图层拆分都跑通了)。

关键接口改动时以官网为准: 图片生成、 模型列表。

真接口核过什么(2026-10-28)

  • 单图:--size 1280x720 出图,落盘 1280×720 PNG;--out X.png 现在会让服务直接给 PNG。
  • 图层拆分:--image 给一张本机图,回来 5 项(1 张底图 + 4 个图层),层名是中文 背景 / 窗户 / 木桌 / 橘猫,图层都是带 alpha 的 PNG,bounding_box.absolute / .normalized 都在。
  • 这一轮真跑时发现并修掉两个只有真接口才暴露的问题:中文层名被清成 layer(现在原样保留),以及 --out X.png 拿到 JPEG 字节(现在扩展名决定 output_format,都没说时默认 png)。
  • 当时的账号还回 ModelNotOpen:方舟的图像模型要在控制台「开通管理」里单独开通,不是默认可用。

还没验的

  • 组图(--count)的真实张数与上限。
  • sequential_image_generation 与 layer_decomposition 在真实模型上的组合约束(脚本只按文档传参)。
  • Windows 上的路径与 base64 参考图(本机是 Linux,只验了 Linux)。