dby-image

---
name: dby-image
description: >-
  AI 生图与改图（都爆鸭）——一句话要一张图就用它：文生图、图生图、改图、主视觉、单独配一张插图。
  给一段描述就出图；给一张参考图（本机文件也行）就在它基础上改。**慢操作**：通常等 1–2 分钟，
  最长 4 分钟，等待期间别中断也别重试（重试就是为同一张图付两次钱）。出图后落成本地文件给你路径。
  触发词：画张图、帮我画、生成图片、生成一张图、AI 出图、出图、文生图、图生图、改图、
  改一下这张图、P 一下、配图、配张图、配一张插图、来张主视觉、做张视觉图、按这个描述画、
  封面、封面图、公众号封面、做张封面、配张封面图、首图灵感。
  不做：只要封面**套路与参考数据**（不出成品图）走 dby-api；把图排进文章存草稿走 dby-publish。
version: 2.3.0
changelog: 出图改按模型分档计价（三档，具体点数看 --describe 实时价，本包不写死数字）；--model 选择表补上价档定性；清掉作废的 quality 段（已停发）
compatibility: >-
  需要 Node ≥18 与环境变量 DOUBAOYA_API_KEY（形如 dyh_…，在 doubaoya.com 密钥中心生成）；
  需要能对 https://doubaoya.com 发 HTTPS 请求。生图计费。
  接口调用经由 dby-api 包的共享 CLI（scripts/lib/locate-dby.mjs 定位），需与 dby-api 一起安装。
---

# AI 生图与改图 · dby-image

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

---

## 怎么用

**在用户的工作目录里跑，用脚本的全路径**——图会落在当前目录，别落进 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   # 按实际安装位置改

# 文生图。比例写进 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 分钟，**中途别打断**。

---

## 🔴 四条红线

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

服务端超时**会退款**，客户端提前放弃**不会**——请求照样跑完、照样扣费；重试 = 为同一张图付两次钱。
额度不足（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 可调
```

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

---

## 这个包管什么、不管什么

| 用户在说 | 归谁 |
|---|---|
| 画张图 / 出图 / 改图 / 文生图 / 图生图 / 主视觉 / 配张插图 / 单独要一张封面 | ✅ **就是这里** |
| 给了参考图，**要保留它的内容**（换一处、加一物） | ✅ 改图，读 [`editing.md`](references/editing.md) |
| 给了参考图，**只要它的感觉**（风格、氛围） | ✅ 不改图：按 [`prompt-ladder.md`](references/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`](references/editing.md)）。改完必须跟原图逐项比，
  不能只看改的那一处。
- **模型爱自己往画面里加字**，密集小字多半是乱码笔画，孤立大字通常没问题。
- 🔴 **它还会自己加半透明水印 / logo**（2026-09-10 实测：没要求文字的图，左上右上各一枚
  描边标记）。上游追加的「不包含水印」拦不住。验收时**四个角单独看一遍**，
  详见 [`visual-review.md`](references/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`（档案里的人设与品牌事实是提示词的合法来源）|

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