dby-image

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI 生图与改图 · dby-image

AI Image Generation and Editing · dby-image

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

Image generation goes through scripts/gen.mjs
— don't hand-craft curl requests.

怎么用

How to Use

在用户的工作目录里跑，用脚本的全路径——图会落在当前目录，别落进 skill 包里。把下面的

$GEN

换成本 skill 的

scripts/gen.mjs

实际路径。

请求由

scripts/gen.mjs

代发；只有绕开脚本自己拼请求时才读

dby-gateway/references/protocol.md

（鉴权、密钥怎么拿、信封与报错码全在那一份）。

bash

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

Run from the user's working directory, using the script's full path — images will be saved to the current directory, not inside the skill package. Replace

$GEN

below with the actual path to this skill's

scripts/gen.mjs

Requests are sent by

scripts/gen.mjs

; only read

dby-gateway/references/protocol.md

if you bypass the script and build requests yourself (authentication, how to get keys, envelope and error codes are all there).

bash

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` 的「选哪个模型」](references/api-contract.md)——那里也写明了
为什么不能向用户承诺「换了就一定更保真」。

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

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


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

---

node "$GEN" --describe


> For details only (price / input contract / output samples) without comparison:
> `node "$SKILL_DIR/scripts/dby.mjs" api describe gpt-image-gen`.

`--out` is relative to the current working directory; if omitted, writes to `doubaoya-image.<ext>` in the current directory.

**Without `--model`, the default tier is used**; the three tiers have different prices (see `--describe` for live prices). To choose, see
[`api-contract.md` — "Which model to choose"](references/api-contract.md) — it also explains
why you can't promise users that "switching will definitely improve fidelity".

**stdout only contains the file path** (can be piped or captured directly); progress and actual dimensions go to stderr:

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


Before calling, tell the user: this step takes a while, usually 1–2 minutes, up to 4 minutes, **don't interrupt midway**.

---

🔴 四条红线

🔴 Four Red Lines

一、失败之后不要重试

1. Don't retry after failure

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

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

Server-side timeout will refund, client-side early abort will not — the request will still complete and still be charged; retrying = paying twice for the same image. Same for insufficient credits (402) and capability unavailable (503).

On failure, stop and honestly tell the user: this attempt may have been charged and the image may already be generated; let the user decide whether to try again.

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

2. Facts in images must not be fabricated either

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

When it involves brand or product facts — names, primary colors, product names, claims, specific numbers — only two sources are allowed: the user's IP profile, or provided by the user on the spot. If unavailable, ask.

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

3. Style belongs to the user, not the assistant

用户没说风格就别替用户加（扁平插画风、纯色背景、不要文字都算）；实测裸提示词出图更丰富。想给建议就从

references/styles.md

里给两三个选项让用户挑。

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

If the user hasn't specified a style, don't add one for them (flat illustration, solid background, no text — all count); in practice, bare prompts produce richer images. Want to give suggestions? Offer two or three options from

references/styles.md

and let the user choose.

⚠️ The upstream adds its own. Tested 2026-09: it rewrites the prompt before generating, and automatically appends exclusions like "no text, no watermark, no logo". This isn't from us, but the user sees the result — so ① don't stack another layer of your own constraints, ② if the user wants text in the image and it doesn't appear, honestly explain this is upstream behavior, and switch to post-processing overlay — don't repeatedly resend the same prompt pretending to bypass it (each round costs money).

四、比例只能写进 prompt

4. Aspect ratio can only be written into the 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 各裁一次）。需要精确像素只能拿到图之后自己裁。脚本每次都打印实测宽高，核一眼。

The

size

parameter is completely ignored by upstream — confirmed again after the 2026-09 upgrade to gpt-image-2.5: request

1024x1024

, actual output 1672×941 / 1731×909, ratio all comes from the "16:9" in the prompt. Write the ratio directly in the description: "wide horizontal, 16:9 ratio" → actual 1672×941. For what ratio to use on each platform, check

prompt-ladder.md

— "Aspect Ratio Quick Reference" (WeChat cover: 16:9, main subject inside center square — WeChat crops at 2.35:1 and center 1:1). For precise pixels you can only crop yourself after getting the image. The script prints actual dimensions every time — check them once.

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

After Image Generation: Acceptance Check (required, free)

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

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

公众号封面多一步、免费：

node scripts/wechat-crops.mjs ./cover.jpg

落出消息列表 2.35:1、转发卡片正中 1:1、 360px 缩略图三张，读回来核「主体与标题在 1:1 里完整、缩略图里标题可读」——微信只收一张封面， 1:1 是裁出来的不是另画一张。

做法：

references/visual-review.md

Read back the just-saved file, check it item by item against this request before delivering.

The checklist is generated from this request (countable elements the user explicitly named, named text, objective constraints added by the assistant), only judge falsifiable things, not aesthetics, zero automatic regeneration.

WeChat cover has one extra free step:

node scripts/wechat-crops.mjs ./cover.jpg

outputs message-list 2.35:1, forward-card center 1:1, and a 360px thumbnail; read them back and verify "subject and title are complete in 1:1, title is readable in thumbnail" — WeChat only accepts one cover, the 1:1 is cropped out, not a separate image.

How:

references/visual-review.md

提示词怎么写

How to Write Prompts

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

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

Default starting point is to send the user's words as-is, only adding objective constraints unavoidable in this scenario (ratio, crop safety zones). When unsatisfied with the output, add only one dimension at a time — adding three at once makes it impossible to tell which didn't work, and each round costs money.

What you need	Where to read
Ladder main entry (most requests just need this)	`prompt-ladder.md`
How to write each of the six dimensions (symptom → which to add)	`axes.md`
Style menu (not defaults)	`styles.md`
Platform scene skeletons	WeChat · Xiaohongshu · Douyin/Video Account/Kuaishou
Editing discipline (what to change + what to keep, anti-drift)	`editing.md`
Parameter tri-state table, `quality` , impossible things	`api-contract.md`

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

WeChat Full-Article Illustration Planning: Plan Positions First (free, no image generation)

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

bash

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

渲染与预上传。

When an entire article needs several images, first use deterministic rules to pick "which h2 section ends get images" + visual suggestions for each, then generate images one by one:

bash

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

Count is tiered by body text length (<1800→3, 1800–3000→4, >3000→5), only picks sections with effective word count ≥160, favoring high-information ones. It only outputs a plan and doesn't modify files: after generating images per the plan, insert

<img src=local path>

at the end of the corresponding h2 section, then hand to

dby-publish

for rendering and pre-upload.

这个包管什么、不管什么

What This Package Handles and Doesn't

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

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

User says	Who handles
Draw an image / generate image / edit image / text-to-image / image-to-image / key visual / add an illustration / just want a cover	✅ This package
Provided a reference image, want its content preserved (change one spot, add one object)	✅ Image editing, read `editing.md`
Provided a reference image, only want its feel (style, mood)	✅ Not editing: reverse-engineer seven items per `prompt-ladder.md` "special entry" and redraw
Viral cover templates / same-track cover reference data	❌ `dby-api` (data retrieval, no image)
Give me a cover plan directly	❌ `dby-api` 's `skill.wechat.coverDesign`
Where to place illustrations in a full article (position planning)	✅ `scripts/plan-figures.mjs` , see previous section
Image pre-upload, cover upload, layout and save as draft	❌ `dby-publish`

When the
dby-publish
pipeline's "cover / illustration" step needs a new image, it calls this package; image uploading and layout still belong to it.

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。用户点名它时如实告知。

Both paths now return PNG (tested after 2026-09 upgrade, ~1–2MB). Previously text-to-image was JPEG — that was because we explicitly requested jpeg at the time; after switching vendors this parameter is no longer sent, format is decided by upstream. The script determines the extension by the
```
mime
```
in the envelope (
```
--out .jpg
```
will still produce png content), downstream code assuming by extension will break.
Reference images are recognized by byte signature, changing the extension won't help. Only png / jpeg / webp are accepted.
More than 3 reference images will be explicitly rejected by the server (tells you the limit, doesn't truncate for anyone); the script errors before sending.
Whether editing preserves the original image's tone and layout is luck. Of two tests, one drifted (see
```
editing.md
```
). After editing, you must compare item by item with the original, not just look at the edited spot.
The model likes to add text to the image itself; dense small text is usually gibberish strokes, isolated big text is usually fine.
🔴 It also adds semi-transparent watermarks / logos on its own (tested 2026-09-10: images without requested text got an outlined mark in each top corner). The upstream's appended "no watermark" doesn't stop it. Check the four corners separately during acceptance, see "Watermark scan" in
```
visual-review.md
```
.
seedream-lite
was de-listed on 2026-08-10, all calls return 503. If the user names it, tell them honestly.

排错

Troubleshooting

现象	处置
`缺 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

当场写成反馈（可忽略，不再重复提）。

Symptom	Action
`Missing DOUBAOYA_API_KEY`	How to get it: see `dby-gateway/references/protocol.md` , `export` then run
`402 INSUFFICIENT_CREDITS`	Insufficient points, tell user to check balance and how to get them at doubaoya.com account page (points are gifted, not sold), don't retry
`401`	Key problem, updating the skill won't fix it
`503 CAPABILITY_UNAVAILABLE`	Don't retry, tell the user honestly
Request incomplete / timeout	Don't retry (see "Don't retry after failure" above). May have been charged, let the user decide
`--describe` exit code 2	This package's parameter knowledge is outdated, update `references/api-contract.md` based on production
`[MISSING_DBY_API]` exit code 3	This package's requests go through `dby-api` , which isn't installed. Run `dby-update` to install the full set, or use `DBY_CLI` to point to it

If you follow this and still can't get around it, or want to complain → you can mention using

dby-feedback

to write feedback on the spot (optional, no need to repeat).

下一步

Next Steps

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

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

Got	Next
Image is done, need to put it into a WeChat article	`dby-publish` (handles image pre-upload, cover upload, and layout)
No article body yet, need the whole article too	`dby-write`
Want to see same-track viral cover approaches first	`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 prompts)

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