# Generate Image

> 调用 ZenMux 中转平台的 openai/gpt-image-2 模型生成 AI 图片（文生图）。当用户要求"生成图片/画一张图/AI画图/做张图/文生图/出图"，或需要把文字描述、提示词变成图片时，必须使用本技能，即使用户没明说"用 AI 生成"。流程为：设计提示词（确定主题/内容/主体元素/尺寸/清晰度，缺失项先用 AskUserQuestion 询问）→ 把完整提示词与参数展示给用户确认 → 确认后调用 scripts/generate_image.py 生成，保存到 AI_output 且文件名与内容相符 → 用视觉模型检查主体是否清晰无遮挡、文字是否完整 → 有问题告知用户，由用户决定是否重新生成。

- Skill: `lingxiaobc/generate-image` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add lingxiaobc/generate-image`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lingxiaobc/generate-image/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lingxiaobc (https://skillmd.com/u/lingxiaobc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lingxiaobc/generate-image

---


# 生成 AI 图片（ZenMux · openai/gpt-image-2）

用 ZenMux 中转平台的 `gpt-image-2` 模型把文字描述生成成图片，保存到 `AI_output/`，并做视觉质检。

## 关键约束（硬性）

1. **模型固定** `gpt-image-2`，端点 `POST https://zenmux.ai/api/v1/images/generations`，认证 `Authorization: Bearer $ZENMUX_API_KEY`，base_url `https://zenmux.ai/api/v1`。
2. **API Key**：从环境变量 `ZENMUX_API_KEY` 读取。若环境无此变量，先向用户索取，**绝不硬编码 key**。
3. **生成一律走脚本** `${CLAUDE_SKILL_DIR}/scripts/generate_image.py`（参数化、含尺寸校验、JSON 输出）。主程序不自己拼 HTTP 请求。
4. **返回是 b64_json**：gpt-image-2 只返回 base64 图片、不返回 url，脚本自动解码落盘。
5. **生成必须经用户确认**：提示词与参数先展示给用户，确认后才调脚本。

## 工作流程

### 1. 明确需求（缺失项用 AskUserQuestion 询问）
需确定：
- **内容 / 主题 / 主体元素**：画什么、主体、风格、构图、色调、是否含文字。
- **尺寸 size**：默认 `1024x1024`。常用 `1024x1024`(方) / `1536x1024`(横) / `1024x1536`(竖) / `auto`；也支持任意 `WIDTHxHEIGHT`（宽高均被 16 整除、比例 1:3~3:1）。
- **清晰度 quality**：`low`/`medium`/`high`/`auto`，默认 `auto`；要高清选 `high`。
- **输出格式 / 背景**：`png`(默认)/`jpeg`/`webp`；需透明背景选 `png` 或 `webp` 并设 `--background transparent`。
用户未明确的，用 **AskUserQuestion 一次性问清**（尺寸、清晰度、是否透明背景），不要自行臆断。

### 2. 构建并展示提示词
- 写出完整、具体、画面感强的提示词（主体 + 风格 + 构图 + 色调 + 细节）。AI 生图对"含文字"的指令要尽量给出确切的文字内容与位置。
- **把提示词全文 + size/quality/格式 列给用户看**，请其确认或修改后再生成。

### 3. 用户确认后，调用脚本生成
```bash
python ${CLAUDE_SKILL_DIR}/scripts/generate_image.py \
  --prompt "<提示词>" \
  --size 1024x1024 --quality high \
  --output AI_output/<与内容相符的文件名>.png
```
- **文件名必须与内容相符**（如 `暑假计划海报.png`、`弹簧振子示意图.png`），放 `AI_output/`，路径用正斜杠；从项目根目录运行。
- 脚本输出 JSON：`{"ok":true,"path":...,"size":...,"usage":...}` 或 `{"ok":false,"error":...,"http_code":...,"retryable":...}`，据此判断成败。

### 4. 视觉质检（生成后必做）
用 **Read 读取刚生成的图片**（Read 支持图片并做视觉理解），重点检查：
- **主体元素是否清晰，有无遮挡 / 变形 / 残缺**；
- **文字是否完整** —— AI 生图常出现"文字生成一半、缺笔画、乱码"，务必逐字核对图中文字；
- 整体是否符合提示词意图。

### 5. 反馈与重生成决策
- 质检若发现问题（主体糊 / 遮挡 / 文字残缺 / 偏离提示词），**如实告知用户具体问题**，**由用户决定是否重新生成**（不擅自重生成）。
- 重生成时可微调提示词或参数（如加强文字指令、换 size/quality）。

## size / quality 速查
- **size**：`1024x1024`(方) / `1536x1024`(横) / `1024x1536`(竖) / `auto`；任意 `WxH` 需 W、H 均被 16 整除、比例 1:3~3:1，最大 3840x2160（2560x1440 以上为实验性）。
- **quality**：`low`(快/省) / `medium` / `high`(最清晰) / `auto`。

## 常见错误
- HTTP 401/403：API Key 无效 / 欠费 / 配额用尽 → 请用户检查 Key 与余额。
- HTTP 422/400 报 size：尺寸不合规 → 改用标准尺寸或确保被 16 整除。
- HTTP 413：prompt 过长（>32000 字符）→ 精简提示词。
- HTTP 429：限流 → 稍后重试。
- 文字残缺 / 主体异常：调提示词重生成（需用户同意）。

## 参考资料
- `${CLAUDE_SKILL_DIR}/scripts/generate_image.py` —— 生成脚本（参数见 `--help`）。
- `${CLAUDE_SKILL_DIR}/references/api-reference.md` —— 完整 API 参数、size 规则、返回结构、错误码、计费。