# Image Gen Kapibala

> 使用 Kapibala 的 OpenAI 兼容图片接口生成/编辑位图图片，默认模型 gpt-image-2。当需要生成图片、编辑已有图片、或批量生成候选图供挑选时触发。触发词："生成图片""画一张""image generation""edit this image""gpt-image-2""批量出图"。

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

---


# image-gen-kapibala

通过 Kapibala 提供的 OpenAI 兼容 Images API 生成/编辑位图图片。本 skill 只有 CLI 一条路径（没有内置图片生成工具可用），默认模型 `gpt-image-2`。

## 前置条件

`~/.zshrc.local` 中需要：

```bash
export KAPIBALA_API_KEY="..."
export KAPIBALA_BASE_URL="https://kapibala.asia/v1"   # 可省略，脚本内置此默认值
```

Preflight 检查：

```bash
[ -n "$KAPIBALA_API_KEY" ] && echo ok || echo "缺少 KAPIBALA_API_KEY，请检查 ~/.zshrc.local 是否已 source"
```

若缺失，提示用户在 `~/.zshrc.local` 添加上面的 `export` 行并重开终端 / `source ~/.zshrc.local`，不要替用户猜测或编造 key。

脚本用 `uv run` 执行，依赖（`openai`、`pillow`）已在脚本头部的 `# /// script` 内联声明，无需提前安装。

## When to use

- 生成新图片（概念图、产品图、封面、hero image）
- 基于参考图生成新图（风格/构图/氛围参考）
- 编辑已有图片（局部重绘、背景替换、去除元素、透明背景抠图）
- 一次产出多张候选图供挑选

## When not to use

- 已有可编辑的 SVG/矢量图标体系，应直接编辑源文件而非生成位图
- 简单形状、图表、示意图更适合用 SVG/HTML/CSS/canvas 直接实现
- 用户明确要求确定性的代码原生输出

## Decision tree

先判断两件独立的事：

1. **意图**：新生成，还是编辑已有图片？
   - 用户提供图片仅作风格/构图/主体参考 → 视为 `generate`
   - 用户想在保留部分内容的前提下修改已有图片 → 视为 `edit`
   - 未提供图片 → 视为 `generate`
2. **执行策略**：单张，还是多张/批量？
   - 多个不同的资产用多次独立的 `generate` 调用或 `generate-batch` 的多个 job，不要用 `--n` 代替——`--n` 只用于同一个 prompt 出多个变体

## Workflow

1. 判断 generate / edit，判断单张 / 批量
2. 收集输入：prompt、精确文字（逐字）、约束/禁止项、参考图或编辑目标图路径
3. 判断输出是预览用还是要落地到当前项目；落地时确定目标路径
4. 按下方"结构化 prompt 模板"整理 prompt；用户 prompt 已经很具体时只做规范化，不要额外加内容
5. 调用脚本（见"用法"）
6. 检查输出：主体、风格、构图、文字准确性、约束是否满足
7. 需要修正时每次只改一处，重新生成并复查
8. 汇报：最终保存路径、最终使用的 prompt/prompt 集合、使用的模型和关键参数（size/quality）

## 用法

生成：

```bash
uv run <skill-dir>/scripts/generate_image.py generate \
  --prompt "a minimal hero image of a ceramic coffee mug, soft studio lighting" \
  --out path/to/output.png \
  [--model gpt-image-2] [--size 1536x1024] [--quality high] [--n 1]
```

编辑（`--image` 可重复传入多张）：

```bash
uv run <skill-dir>/scripts/generate_image.py edit \
  --prompt "change only the background to a warm sunset gradient; keep the product unchanged" \
  --image path/to/source.png \
  --out path/to/edited.png
```

批量（JSONL，每行一个 job，字符串或 `{"prompt": "...", "out": "...", ...}` 对象均可）：

```bash
uv run <skill-dir>/scripts/generate_image.py generate-batch \
  --input jobs.jsonl \
  --out-dir output/imagegen/batch/
```

先用 `--dry-run` 预览最终请求体和输出路径，确认无误再正式执行。

`--out` 已存在文件默认不覆盖，需要覆盖用 `--force`；需要额外一份缩略图用 `--downscale-max-dim <px>`。

## 参数速查

| 参数 | 说明 |
|------|------|
| `--model` | 默认 `gpt-image-2` |
| `--size` | `auto` 或 `WIDTHxHEIGHT`；`gpt-image-2` 见下方尺寸规则 |
| `--quality` | `low`/`medium`/`high`/`auto`；草稿用 `low`，终稿用 `high`/`auto` |
| `--background` | `transparent`/`opaque`/`auto`；`gpt-image-2` 不支持 `transparent` |
| `--n` | 同一 prompt 的变体数（1-10） |
| `--out` / `--out-dir` | 单文件路径 / 批量输出目录 |
| `--input-fidelity` | 仅 `edit` 支持，`gpt-image-2` 不支持此参数（固定高保真） |

## gpt-image-2 尺寸规则

`size` 为 `auto` 或满足以下全部约束的 `WIDTHxHEIGHT`：

- 最长边 `<= 3840px`
- 宽高都是 `16px` 的倍数
- 长边:短边 `<= 3:1`
- 总像素在 `655,360` 到 `8,294,400` 之间

常用尺寸：`1024x1024`（方形快稿）、`1536x1024`/`1024x1536`（横/竖版）、`2048x2048`（2K 方形）、`3840x2160`/`2160x3840`（4K 横/竖）。

## 结构化 prompt 模板

```text
Use case: <场景，如 product-mockup / ui-mockup / illustration-story>
Primary request: <用户核心诉求>
Scene/background: <环境/背景>
Subject: <主体>
Style/medium: <照片/插画/3D 等>
Composition/framing: <构图>
Lighting/mood: <光线与氛围>
Color palette: <配色>
Materials/textures: <材质>
Text (verbatim): "<需要出现的精确文字>"
Constraints: <必须保留的内容>
Avoid: <禁止出现的内容>
```

只保留有帮助的字段，不要为了凑格式硬填。脚本内置 `--use-case`/`--scene`/`--subject`/... 等参数会自动拼成上述结构（默认开启，`--no-augment` 关闭）。

编辑任务务必显式列出不变量，例如 "change only the background; keep the product and its edges unchanged"，每轮迭代都重复一遍以减少漂移。

## Troubleshooting

- 报错缺少 `KAPIBALA_API_KEY`：检查 `~/.zshrc.local` 是否配置并已 `source`，不要代替用户猜测 key
- 429 / 超时：`generate-batch` 内置指数退避重试（`--max-attempts`，默认 3 次）；单张 `generate`/`edit` 失败需手动重试
- 输出已存在报错：加 `--force` 覆盖，或换路径