dby-image

AI image generation and editing · dby-image

Image generation goes through scripts/gen.mjs, don't hand-roll curl yourself.

How to use

Run it in the user's working directory, using the script's full path— images will land in the current directory, not inside the skill package. Replace the following $GEN with this skill's scripts/gen.mjs actual path.

Requests are sent on your behalf by scripts/gen.mjs ; read this only when bypassing the script and assembling requests yourself dby-gateway/references/protocol.md (auth, how to obtain the key, the envelope, and error codes are all in that one document).

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

Text-to-image. Write the aspect ratio into the prompt (the size parameter is invalid, see below)

node "$GEN" "A small yellow duck wearing a scarf standing in the snow, cartoon illustration style. Wide landscape orientation, 16:9 aspect ratio." --out duck.jpg

Image editing. --ref can be a local file path, a public URL, or a data: URI; write it multiple times for multiple images, up to 3

node "$GEN" "Only change the scarf to blue, keep everything else exactly unchanged: do not alter the duck's design, pose, snowy scene, or composition."
--ref ./duck.jpg --out duck2.png

Reconciliation: pull the live production contract and check whether this package's understanding of the parameters is outdated (free, no image generated)

node "$GEN" --describe


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

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

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

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

✅ 129KB measured 1672x941 ratio 1.777 took 37s


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

---

## 🔴 四条红线

### 一、失败之后不要重试

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

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

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

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

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

用户没说风格就**别替用户加**（扁平插画风、纯色背景、不要文字都算）；实测裸提示词出图更丰富。
想给建议就从 [`references/styles.md`](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` 的「比例速查」](references/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`](references/visual-review.md)

---

## 提示词怎么写

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

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

---

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

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

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

The number of images is tiered by the body text word count (<1800→3, 1800–3000→4, >3000→5); only select sections with an effective word count ≥160, favoring those with more information. It only produces a plan and does not modify files: after generating images one by one according to the plan, insert <img src=本地路径> into the corresponding h2 sectionend, then hand off to dby-publish for rendering and pre-upload.

What this package covers and does not cover

The user is saying	Whose job it is
Draw an image / generate an image / edit an image / text-to-image / image-to-image / key visual / add an illustration / request a single cover	✅ This is the one
A reference image was given,its content needs to be preserved(change one spot, add one object)	✅ Image editing, read `editing.md`
A reference image was given,only its feel is wanted(style, atmosphere)	✅ No image editing: infer the seven items and redraw based on `prompt-ladder.md` "special entry points"
viral cover formulas / cover reference data for the same niche	❌ `dby-api`(data retrieval, no image generated)
Just give me a version of the coverplan	❌ `dby-api` 's `skill.wechat.coverDesign`
illustrations for the entire articlewhere to place them(placement planning)	✅ `scripts/plan-figures.mjs`, see the previous section
image pre-upload, cover upload, layout saved as draft	❌ `dby-publish`

dby-publish pipeline's "cover / illustrations" step calls on this package when it needs new images; uploading and arranging images still belongs to it.

Gotchas

Both paths now return PNG(measured after the 2026-09 switch, about 1–2MB). Previously text-to-image was JPEG— that was because we explicitly requested jpeg at the time; after switching providers this parameter is no longer sent, and the format is decided upstream. The script uses the mime in the envelope to determine the extension (--out writes .jpg will also end up as png content), so downstream assumptions based on the extension will fall flat.
Reference images are identified by byte signature, so changing the extension does nothing. only accepts png / jpeg / webp.
More than 3 reference images will be explicitly rejected by the server(the limit is stated, no truncation on anyone's behalf); the script errors out before sending.
Whether image editing preserves the original's color tone and layout is a matter of luck. In two real tests it drifted once (see editing.md). After editing you must compare item by item with the original, not just look at the part that was changed.
The model loves adding text into the image on its own, dense small text is mostly garbled strokes, isolated large text is usually fine.
🔴 It also adds semi-transparent watermarks / logos on its own(measured 2026-09-10: for an image with no text requested, one outlined mark each in the top-left and top-right). The upstream-added "no watermark" cannot stop it. During acceptance,check the four corners individually, see visual-review.md under "watermark scan".
seedream-lite was taken offline on 2026-08-10, all calls return 503. When a user names it, tell them truthfully.

Troubleshooting

Symptom	Handling
`缺 DOUBAOYA_API_KEY`	How to get it, see `dby-gateway/references/protocol.md`，`export` then run again
`402 INSUFFICIENT_CREDITS`	Insufficient points, tell the user to check the balance and how to obtain it on the doubaoya.com account page (points are only gifted, not sold),do not retry
`401`	Key issue, updating the skill won't fix it
`503 CAPABILITY_UNAVAILABLE`	do not retry, tell them truthfully
Request not completed / timed out	do not retry(main text "do not retry after failure"). May have been charged, leave it to the user to decide
`--describe` exit code 2	This package's parameter knowledge is outdated, go by production to fix `references/api-contract.md`
`[MISSING_DBY_API]` exit code 3	This package's requests go through `dby-api`, which is not installed. Run `dby-update` to install the full set, or use `DBY_CLI` to point the way

If following it still doesn't get around the problem, or you want to complain → you can mention using dby-feedback to write it up as feedback on the spot (can be ignored, no need to mention it again).

Next step

What you get	Next step
The image is ready, want to put it into a WeChat official account article	`dby-publish`(handles image pre-upload, cover upload and layout)
No body text yet, want the article together	`dby-write`
Want to first see how viral covers in the same niche are made	`dby-api`(data retrieval)
Don't know what style to draw	`dby-charter`(the persona and brand facts in the profile are legitimate sources for the prompt)

If you only need one image, stop at this package, don't run any of the above.