dby-image

AI 生图与改图 · dby-image

出图走 scripts/gen.mjs，别自己手搓 curl。

---

怎么用

在用户的工作目录里跑，用脚本的全路径——图会落在当前目录，别落进 skill 包里。 把下面的 $GEN 换成本 skill 的 scripts/gen.mjs 实际路径。

请求由 scripts/gen.mjs 代发；只有绕开脚本自己拼请求时才读 dby-gateway/references/protocol.md （鉴权、密钥怎么拿、信封与报错码全在那一份）。

export DOUBAOYA_API_KEY="dyh_你的密钥"     # 绝不打印、不写文件、不回显给用户
GEN=~/.claude/skills/dby-image/scripts/gen.mjs   # 按实际安装位置改

# 文生图。比例写进 prompt（size 参数无效，见下）
node "$GEN" "一只戴围巾的黄色小鸭子站在雪地里，卡通插画风。宽幅横版，16:9 比例。" --out duck.jpg

# 改图。--ref 可以是本机文件路径、公网 URL 或 data: URI，写几次就是几张，最多 3 张
node "$GEN" "只把围巾换成蓝色，其余全部保持不变：鸭子造型、姿势、雪地场景、构图都不要动。" \
  --ref ./duck.jpg --out duck2.png

# 对账：拉生产实时契约，核本包的参数认知有没有过期（免费，不出图）
node "$GEN" --describe

只想看详情（价格 / 入参契约 / 输出样例）不做比对： node "$SKILL_DIR/scripts/dby.mjs" api describe gpt-image-gen。

--out 相对当前工作目录；不给就写成当前目录的 doubaoya-image.<ext>。

--model 不传走默认档；三档价钱不同（--describe 看实时价），要挑就看 api-contract.md 的「选哪个模型」——那里也写明了 为什么不能向用户承诺「换了就一定更保真」。

stdout 只有文件路径（可直接管道／取变量），进度和实测宽高走 stderr：

✅ 129KB  实测 1672x941  比例 1.777  耗时 37s

调用前告诉用户一句：这一步要等一会儿，通常 1–2 分钟，最长 4 分钟，中途别打断。

---

🔴 四条红线

一、失败之后不要重试

服务端超时会退款，客户端提前放弃不会——请求照样跑完、照样扣费；重试 = 为同一张图付两次钱。 额度不足（402）和能力不可用（503）同理。

失败就停下来如实告诉用户：这次可能已经扣费、图可能已经生成，要不要再来由用户决定。

二、图里的事实同样不许编造

涉及品牌或产品事实时——名称、主色、产品名、承诺、具体数字—— 只许来自两个地方：用户的 IP 档案，或用户当场给出。取不到就问。

三、风格是用户的，不是助手的

用户没说风格就别替用户加（扁平插画风、纯色背景、不要文字都算）；实测裸提示词出图更丰富。 想给建议就从 references/styles.md 里给两三个选项让用户挑。

⚠️ 上游自己会加。 2026-09 实测：它把提示词重写一遍才拿去出图，并自动追加 「不包含文字、水印、标志」这类排除项。这不是我们加的，但用户看到的是结果—— 所以①别再叠一层自己的限定，②用户要图内文字却没画出来时，如实说明这是上游行为， 改走后期叠加，别反复重发同一条提示词假装能绕过（每一轮都花钱）。

四、比例只能写进 prompt

size 参数上游完全忽略——2026-09 换代到 gpt-image-2.5 后复测仍然如此： 请求 1024x1024，实际出图 1672×941 / 1731×909，比例全部来自提示词里那句「16:9」。 要什么比例就在描述里直接写数字：「宽幅横版，16:9 比例」→ 实测 1672×941。各平台该写什么比例查 prompt-ladder.md 的「比例速查」（公众号封面：16:9，主体进居中正方形——微信按 2.35:1 与正中 1:1 各裁一次）。 需要精确像素只能拿到图之后自己裁。脚本每次都打印实测宽高，核一眼。

---

出图之后：验收（必做，不花钱）

读回刚落盘的文件，对着这次的请求逐条核一遍再交付。

核对表从这次的请求生成（用户点名的可数元素、点名的文字、助手加的客观约束）， 只判可证伪的，不判好不好看，零自动重出。

公众号封面多一步、免费：node scripts/wechat-crops.mjs ./cover.jpg 落出消息列表 2.35:1、转发卡片正中 1:1、 360px 缩略图三张，读回来核「主体与标题在 1:1 里完整、缩略图里标题可读」——微信只收一张封面， 1:1 是裁出来的不是另画一张。

做法：references/visual-review.md

---

提示词怎么写

默认起点是把用户的话原样送出去，只加这个场景客观躲不掉的约束（比例、裁切安全区）。 出图不满意时一次只补一个维度——同时加三个就分不清哪个没生效，而每一轮都花钱。

要什么	读哪儿
阶梯主入口（绝大多数请求读完它就够）	prompt-ladder.md
六个维度的具体写法（症状 → 补哪个）	axes.md
风格菜单（不是默认值）	styles.md
平台场景骨架	公众号 · 小红书 · 抖音视频号快手
改图纪律（改什么 + 保留什么、防漂）	editing.md
参数三态表、quality、做不到的事	api-contract.md

---

公众号整篇配图：先规划位置（免费、不出图）

整篇文章要配几张图时，先用确定性规则挑「在哪些 h2 小节末尾放图」+ 每张画面建议，再逐张出图：

node scripts/plan-figures.mjs --md 文章.md    # 纯本机不接 LLM；--max-figures/--min-chars/--json 可调

张数按正文字数分档（<1800→3、1800–3000→4、>3000→5），只挑有效字数 ≥160 的小节，偏向信息量大的。 它只出方案不改文件：按方案逐张出图后，把 <img src=本地路径> 插进对应 h2 小节末尾， 再交 dby-publish 渲染与预上传。

---

这个包管什么、不管什么

用户在说	归谁
画张图 / 出图 / 改图 / 文生图 / 图生图 / 主视觉 / 配张插图 / 单独要一张封面	✅ 就是这里
给了参考图，要保留它的内容（换一处、加一物）	✅ 改图，读 editing.md
给了参考图，只要它的感觉（风格、氛围）	✅ 不改图：按 prompt-ladder.md 「特殊入口」反推七项重画
爆款封面套路 / 同赛道封面参考数据	❌ dby-api（取数，不出图）
直接给我一版封面方案	❌ dby-api 的 skill.wechat.coverDesign
整篇文章的配图放哪儿（位置规划）	✅ scripts/plan-figures.mjs，见上节
图片预上传、封面上传、排版存草稿	❌ dby-publish

dby-publish 流水线「封面 / 配图」一步需要新图时点名本包；图片的上传与排布仍归它。

---

Gotchas

• 两条路径现在都返回 PNG（2026-09 换代后实测，约 1–2MB）。此前文生图是 JPEG—— 那是因为我方当时显式要求 jpeg，换供应商后这个参数已不再发送，格式由上游定。 脚本按信封里的 mime 定扩展名（--out 写 .jpg 也会落成 png 内容）， 下游若按扩展名做假设会踩空。
• 参考图按字节签名认类型，改扩展名没用。 只收 png / jpeg / webp。
• 参考图超过 3 张会被服务端明确拒掉（告知上限，不替谁截断）；脚本在发出去之前就报错。
• 改图会不会保住原图的色调和版面，看运气。 两次实测漂了一次 （详见 editing.md）。改完必须跟原图逐项比， 不能只看改的那一处。
• 模型爱自己往画面里加字，密集小字多半是乱码笔画，孤立大字通常没问题。
• 🔴 它还会自己加半透明水印 / logo（2026-09-10 实测：没要求文字的图，左上右上各一枚 描边标记）。上游追加的「不包含水印」拦不住。验收时四个角单独看一遍， 详见 visual-review.md 的「扫水印」。
• seedream-lite 已于 2026-08-10 下架，调用一律 503。用户点名它时如实告知。

---

排错

现象	处置
缺 DOUBAOYA_API_KEY	怎么拿见 dby-gateway/references/protocol.md，export 后再跑
402 INSUFFICIENT_CREDITS	点数不足，提示用户到 doubaoya.com 账户页查看余额与获取方式（点数只赠不卖），不要重试
401	密钥问题，更新 skill 治不了
503 CAPABILITY_UNAVAILABLE	不要重试，如实告知
请求未完成 / 超时	不要重试（正文「失败之后不要重试」）。可能已扣费，交给用户决定
--describe 退出码 2	本包的参数认知过期了，以生产为准去改 references/api-contract.md
[MISSING_DBY_API] 退出码 3	本包的请求经由 dby-api，它没装。跑 dby-update 装全集，或用 DBY_CLI 指路

照做仍绕不过去、或想吐槽 → 可提一句用 dby-feedback 当场写成反馈（可忽略，不再重复提）。

---

下一步

拿到什么	下一步
图出好了，要放进公众号文章	dby-publish（管图片预上传、封面上传与排版）
还没有正文，要连文章一起	dby-write
想先看同赛道爆款封面怎么做	dby-api（取数）
不知道该画什么风格	dby-charter（档案里的人设与品牌事实是提示词的合法来源）

只要一张图就停在本包，上面这些一个都不要跑。