---
name: gemini-image-api
description: Use when需要通过 ToAPIs 的官方图片接口做文生图或参考图重绘，尤其适合需要稳定异步任务、可轮询状态、可上传本地参考图，以及在 gpt-4o-image、Gemini、Flux、Seedream、Grok 等模型之间按成本或质量切换的场景。
---

# ToAPIs 图像生成 Skill（兼容原 gemini-image-api 路径）

这个 skill 现在的**默认推荐链路**已经切到 ToAPIs 官方图片接口；保留原来的 skill 名称只是为了兼容既有调用路径。

- Skill 路径：`$HOME/.claude/skills/gemini-image-api`
- **Best URL**：`https://toapis.com`
- 默认调试模型：`gpt-4o-image`
- 当前支持更丰富的模型家族：
  - GPT-4o
  - Gemini
  - Flux
  - Seedream
  - Grok

---

## 这次固化的默认策略（2026-04-06）

### 1) 默认入口

- **创建任务**：`POST https://toapis.com/v1/images/generations`
- **查询状态**：`GET https://toapis.com/v1/images/generations/{task_id}`
- **上传本地参考图**：`POST https://toapis.com/v1/uploads/images`

### 2) 默认调试模型

按你提供的 `$HOME/Downloads/文字生图的模型配置价格单.png`，这次默认调试仍固定为：

```text
gpt-4o-image
```

原因：

- 你明确要求“不要用贵模型调试”
- 当前这套 skill 的默认职责是**低成本验证链路**
- 真实联调已经跑通

### 3) 一句话选型建议

- **最便宜调试**：`gpt-4o-image`
- **Gemini 低成本首选**：`gemini-2.5-flash-image-preview`
- **Gemini 更推荐的均衡款**：`gemini-3.1-flash-image-preview`
- **Gemini 高质量正式出图**：`gemini-3-pro-image-official`
- **风格化/重绘更强**：`flux-kontext-pro` / `flux-kontext-max`
- **中文海报/质感图**：`doubao-seedream-4-5` / `doubao-seedream-5-0`

---

## 配置文件

默认读取：

```bash
$HOME/.claude/skills/gemini-image-api/.env
```

推荐内容：

```bash
GEMINI_BASE_URL=https://toapis.com
GEMINI_API_KEY=<REDACTED>
GEMINI_OPENAI_TIMEOUT_SECONDS=900
```

安全模板：

```bash
$HOME/.claude/skills/gemini-image-api/.env.example
```

---

## 内置模型目录

你现在可以直接列出内置模型，不必手记所有模型名：

```bash
python $HOME/.claude/skills/gemini-image-api/scripts/gemini_generate.py --list-models
```

只看 Gemini：

```bash
python $HOME/.claude/skills/gemini-image-api/scripts/gemini_generate.py \
  --list-models \
  --family gemini \
  --show-aliases
```

如果你后面做 **Web coding / 前端表单 / 后端 API 包装**，想直接程序化读取模型目录，可以直接拿 JSON：

```bash
python $HOME/.claude/skills/gemini-image-api/scripts/gemini_generate.py \
  --list-models \
  --json
```

或者直接读取已经沉淀好的静态目录文件：

```bash
$HOME/.claude/skills/gemini-image-api/references/model_catalog.json
```

支持的家族：

- `all`
- `gemini`
- `gpt4o`
- `flux`
- `seedream`
- `grok`

---

## 当前内置的常用模型

### 1) GPT-4o

| 模型 | 适用场景 |
|------|----------|
| `gpt-4o-image` | **默认最低成本调试**、快速验证 prompt、通用生成与编辑 |

### 2) Gemini

| 模型 | 适用场景 |
|------|----------|
| `gemini-2.5-flash-image-preview` | Gemini 低成本快速出图 |
| `gemini-3.1-flash-image-preview` | **Gemini 推荐均衡款**，质量/速度/成本更平衡 |
| `gemini-2.5-flash-image-official` | 想走更官方稳定的 2.5 Flash |
| `gemini-3.1-flash-image-preview-official` | 想走更官方稳定的 3.1 Flash |
| `gemini-3-pro-image` | 更高质量 Gemini 生成 |
| `gemini-3-pro-image-official` | **Gemini 正式高质量出图** |

### 3) Flux

| 模型 | 适用场景 |
|------|----------|
| `flux-kontext` | 通用风格化、图像编辑 |
| `flux-kontext-pro` | 风格控制更稳、细节更强 |
| `flux-kontext-max` | 高质量风格化最终图 |
| `flux-2-flex` | 快速多轮迭代 |
| `flux-2-pro` | 质感图、较高质量最终图 |

### 4) Seedream

| 模型 | 适用场景 |
|------|----------|
| `doubao-seedream-4-5` | 中文语义理解较强、电商海报、视觉图 |
| `doubao-seedream-5-0` | Seedream 更新一代，更适合高质量最终图 |

### 5) Grok

| 模型 | 适用场景 |
|------|----------|
| `grok-4-1-image` | Grok 图像生成基础款 |
| `grok-4-2-image` | Grok 更高质量版本 |

---

## 友好别名

为了避免每次都记长模型名，脚本内置了一批常用别名。

例如：

| 别名 | 实际模型 |
|------|----------|
| `nano-banana` | `gemini-2.5-flash-image-preview` |
| `nano-banana2` | `gemini-3.1-flash-image-preview` |
| `gemini-pro` | `gemini-3-pro-image-official` |
| `flux-pro` | `flux-2-pro` |
| `seedream` | `doubao-seedream-5-0` |
| `grok-image` | `grok-4-1-image` |

所以你现在可以直接这样写：

```bash
python $HOME/.claude/skills/gemini-image-api/scripts/gemini_generate.py \
  "做一张未来科技感横幅" \
  --model nano-banana2 \
  --aspect-ratio 16:9 \
  --output banner.png
```

---

## 推荐使用路径

### 场景 A：最低成本调试

```bash
python $HOME/.claude/skills/gemini-image-api/scripts/gemini_generate.py \
  "一只极简线稿风格的小猫头像，白底，单主体"
```

### 场景 B：Gemini 低成本可用

```bash
python $HOME/.claude/skills/gemini-image-api/scripts/gemini_generate.py \
  "赛博朋克风格的城市夜景，霓虹灯闪烁" \
  --model gemini-2.5-flash-image-preview \
  --aspect-ratio 16:9 \
  --image-size 2K \
  --output gemini-25-flash.png
```

### 场景 C：Gemini 更推荐的均衡款

```bash
python $HOME/.claude/skills/gemini-image-api/scripts/gemini_generate.py \
  "赛博朋克风格的城市夜景，霓虹灯闪烁，适合做网页横幅" \
  --model gemini-3.1-flash-image-preview \
  --aspect-ratio 16:9 \
  --image-size 2K \
  --output gemini-31-flash.png
```

### 场景 D：Gemini 高质量正式出图

```bash
python $HOME/.claude/skills/gemini-image-api/scripts/gemini_generate.py \
  "高质量未来感产品主视觉，电影级光影，细节丰富" \
  --model gemini-3-pro-image-official \
  --aspect-ratio 16:9 \
  --image-size 4K \
  --output gemini-pro-final.png
```

### 场景 E：Flux 风格化重绘

```bash
python $HOME/.claude/skills/gemini-image-api/scripts/gemini_generate.py \
  "把它改成赛博朋克风格，但保留主体构图" \
  --model flux-kontext-pro \
  --input reference.png \
  --output flux-edited.png
```

### 场景 F：Seedream 中文视觉图

```bash
python $HOME/.claude/skills/gemini-image-api/scripts/gemini_generate.py \
  "为医学 AI 工具做一张中文风格海报，信息感强，蓝紫色科技风" \
  --model doubao-seedream-5-0 \
  --aspect-ratio 3:4 \
  --image-size 4K \
  --output seedream-poster.png
```

---

## 其他常用命令

### 1) 从长 prompt 文件读取

```bash
python $HOME/.claude/skills/gemini-image-api/scripts/gemini_generate.py \
  --prompt-file prompt.txt \
  --model gpt-4o-image \
  --output output.png
```

### 2) 使用本地参考图重绘

```bash
python $HOME/.claude/skills/gemini-image-api/scripts/gemini_generate.py \
  "把它改成赛博朋克风格，但保留主体构图" \
  --model gpt-4o-image \
  --input reference.png \
  --output edited.png
```

### 3) 查看当前配置来源

```bash
python $HOME/.claude/skills/gemini-image-api/scripts/gemini_generate.py \
  --print-config-source \
  "测试提示词"
```

### 4) 只做 dry-run

```bash
python $HOME/.claude/skills/gemini-image-api/scripts/gemini_generate.py \
  --dry-run \
  --model nano-banana2 \
  "测试提示词"
```

---

## 现在脚本的行为

当 `GEMINI_BASE_URL=https://toapis.com` 时：

1. 文生图：直接走 ToAPIs 官方异步任务接口
2. 有 `--input` 时：先上传本地图片，再把返回 URL 传给生成任务
3. 自动轮询任务状态直到完成
4. 自动下载最终图片到本地输出路径

当你把 `--base-url` 改成**非 ToAPIs** 的其他旧 provider 时：

- 脚本仍保留 legacy 路径：
  - 原生 `/v1beta`
  - 同地址 `/v1` OpenAI fallback

所以它现在是：

- **ToAPIs 官方异步接口优先**
- **旧 provider 兼容保留**

---

## 命令行参数

| 参数 | 说明 |
|------|------|
| `prompt` | 图像描述或编辑指令 |
| `--prompt-file` | 从文本文件读取长提示词 |
| `--model` / `-m` | 模型名称或友好别名，默认 `gpt-4o-image` |
| `--list-models` | 打印内置模型目录并退出 |
| `--family` | 配合 `--list-models` 使用，按家族筛选 |
| `--show-aliases` | 配合 `--list-models` 使用，显示友好别名 |
| `--json` | 配合 `--list-models` 使用，输出机器可读 JSON |
| `--output` / `-o` | 输出文件路径 |
| `--input` / `-i` | 输入图像路径（会先上传再生成） |
| `--aspect-ratio` / `-a` | 宽高比，如 `1:1`、`16:9` |
| `--image-size` / `-s` | 分辨率提示；Gemini / Flux / Seedream 通常更值得显式设置 |
| `--base-url` / `-b` | 手工覆盖 API 地址 |
| `--api-key` / `-k` | 手工覆盖 API Key |
| `--print-config-source` | 打印配置来源 |
| `--dry-run` | 不发请求，只打印执行摘要 |

---

## 注意事项

1. `.env` 已改为**本地保留，不再纳入 Git 跟踪**
2. 若需要提交到 GitHub，只提交：
   - `SKILL.md`
   - `scripts/`
   - `references/`
   - `.env.example`
3. 不要提交真实 API Key
4. 若只是调试链路，优先 `gpt-4o-image`
5. 若要正式高质量图件，再显式切换 `gemini-3-pro-image-official`、`flux-kontext-max`、`doubao-seedream-5-0` 这类模型

---

## 参考文档

- GPT-4o Image Generation  
  https://docs.toapis.com/docs/en/api-reference/images/gpt-4o/generation
- Gemini-3.1-Flash Official Image Generation  
  https://docs.toapis.com/docs/en/api-reference/images/gemini-3.1-flash-official/generation
- Gemini-3-Pro Official Image Generation  
  https://docs.toapis.com/docs/en/api-reference/images/gemini-3-pro-image-official/generation
- Flux Kontext Image Generation  
  https://docs.toapis.com/docs/en/api-reference/images/flux-kontext/generation
- Flux 2.0 Image Generation  
  https://docs.toapis.com/docs/en/api-reference/images/flux-2/generation
- Seedream-5.0 Image Generation  
  https://docs.toapis.com/docs/en/api-reference/images/seedream-5.0/generation
- 图片任务状态  
  https://docs.toapis.com/docs/cn/api-reference/tasks/image-status
- 图片上传  
  https://docs.toapis.com/docs/cn/api-reference/uploads/images
