# Nano Banana

> 文生图工具，基于 tu-zi.com API，支持 GPT-image、Gemini、集梦等多种模型。当用户需要 AI 绘画、文生图、图片生成时使用。

- Skill: `qcqallen/nano-banana` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add qcqallen/nano-banana`
- Raw SKILL.md: https://api.skillmd.com/api/skills/qcqallen/nano-banana/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: qcqAllen (https://skillmd.com/u/qcqallen)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/qcqallen/nano-banana

---


# Nano Banana 文生图 Skill

基于 tu-zi.com API 的文本生成图片工具，支持多种 AI 模型。

## When to Use This Skill

在以下情况触发：
- 用户明确提到「文生图」、「AI 绘画」、「图片生成」
- 用户提到「nano-banana」
- 需要根据文本描述生成图片
- 为文章生成插图或封面图

## Not For / Boundaries

- **仅用于**文本生成图片，不支持图片编辑或修复
- **需要**有效的 tu-zi.com API Key（环境变量 `TU_ZI_API_KEY`）
- 默认使用 `gpt-image-2` 模型
- 支持切换到其他模型（GPT-image、Gemini、集梦）

## Quick Reference

### 基础使用

**模式 1：** 简单文生图（使用默认模型 gpt-image-2）
```bash
python ~/.claude/skills/nano-banana/scripts/nano_banana.py "画个海洋世界"
```

**模式 2：** 指定模型（支持别名）
```bash
# 使用 Gemini（别名）
python ~/.claude/skills/nano-banana/scripts/nano_banana.py "日落" --model gemini

# 使用集梦（别名）
python ~/.claude/skills/nano-banana/scripts/nano_banana.py "可爱的猫" --model seedream

# 使用完整模型名
python ~/.claude/skills/nano-banana/scripts/nano_banana.py "prompt" --model gemini-3-pro-image-preview
```

**模式 3：** 指定输出路径和尺寸
```bash
python ~/.claude/skills/nano-banana/scripts/nano_banana.py "prompt" --output output.png --size 1024x1024
```

### 列出所有支持的模型

```bash
python ~/.claude/skills/nano-banana/scripts/nano_banana.py --list-models
```

## 模型别名

可以使用简短的别名来指定模型：

| 别名 | 映射模型 |
|------|----------|
| `gpt` | `gpt-image-2` |
| `gpt-image` | `gpt-image-2` |
| `gemini` | `gemini-3.1-flash-image-preview` |
| `gemini-pro` | `gemini-3-pro-image-preview` |
| `gemini-flash` | `gemini-3.1-flash-image-preview` |
| `seedream` | `doubao-seedream-5-0-260128` |
| `seedream-5` | `doubao-seedream-5-0-260128` |
| `seedream-4.5` | `doubao-seedream-4-5-251128` |
| `seedream-4` | `seedream-4-0-250828` |

## 支持的模型

### OpenAI GPT-image

| 模型 | 说明 |
|------|------|
| `gpt-image-2` | 默认模型，支持任意分辨率 |
| `gpt-image-1.5` | GPT-image-1.5 |

**特点：**
- size 格式：像素尺寸（如 `1024x1024`）或宽高比（如 `1:1`）
- 支持 `quality` 参数：`auto`, `low`, `medium`, `high`
- 支持 `n` 参数（生成多张）
- 支持 `style` 参数：`vivid`, `natural`

### Google Gemini

| 模型 | 说明 |
|------|------|
| `gemini-3-pro-image-preview` | 支持 4K |
| `gemini-3.1-flash-image-preview` | 2025年2月新上线 |

**特点：**
- size 格式：`1x1`, `16x9`, `4x3` 等
- 支持 `quality` 参数：`1k`, `2k`, `4k`

### 字节跳动集梦 (Seedream)

| 模型 | 说明 |
|------|------|
| `doubao-seedream-5-0-260128` | 集梦 5.0，支持 1K-3K |
| `doubao-seedream-4-5-251128` | 集梦 4.5，支持 1K-4K |
| `seedream-4-0-250828` | 集梦 4.0，支持 1K-4K |

**特点：**
- size 格式：`1K`, `2K`, `4K` 或像素尺寸
- 支持 `seed` 参数（随机种子）
- 支持 `watermark` 参数（水印）
- 支持 `guidance_scale` 参数（引导比例）

## 高级配置

### 尺寸设置

不同模型的 size 参数格式不同，脚本会自动转换：

```bash
# GPT-image-2: 使用像素尺寸
python nano_banana.py "prompt" --model gpt-image-2 --size 1024x1024

# Gemini: 使用宽高比格式
python nano_banana.py "prompt" --model gemini-3.1-flash-image-preview --size 16x9

# 集梦: 使用质量等级
python nano_banana.py "prompt" --model doubao-seedream-5-0-260128 --size 4K

# 通用: 使用宽高比（脚本会自动转换）
python nano_banana.py "prompt" --size 16:9
```

### 质量设置

```bash
# GPT-image-2
python nano_banana.py "prompt" --model gpt-image-2 --quality high

# Gemini
python nano_banana.py "prompt" --model gemini-3.1-flash-image-preview --quality 4k
```

### 集梦特有参数

```bash
# 设置随机种子
python nano_banana.py "prompt" --model doubao-seedream-5-0-260128 --seed 42

# 禁用水印
python nano_banana.py "prompt" --model doubao-seedream-5-0-260128 --watermark false

# 设置引导比例
python nano_banana.py "prompt" --model doubao-seedream-5-0-260128 --guidance-scale 5.0
```

## Python API 使用

```python
from nano_banana import NanoBanana

# 初始化
generator = NanoBanana(api_key="your-key")

# 使用默认模型 (gpt-image-2)
image_path = generator.generate("画个海洋世界", save_path="ocean.jpg")

# 使用 Gemini
image_path = generator.generate("日落", model="gemini-3.1-flash-image-preview", size="16x9")

# 使用集梦
image_path = generator.generate("可爱的猫", model="doubao-seedream-5-0-260128", size="4K")

# 集梦特有参数
image_path = generator.generate(
    "prompt",
    model="doubao-seedream-5-0-260128",
    seed=42,
    watermark=False,
    guidance_scale=5.0
)
```

## Examples

### Example 1: 基础文生图

- **Input:** `"画个海洋世界"`
- **Steps:**
  1. 实例化 `NanoBanana`
  2. 调用 `generate("画个海洋世界", save_path="ocean.jpg")`
- **Expected output:** `ocean.jpg` 文件保存到当前目录

### Example 2: 使用不同模型生成

- **Input:** 需要使用不同模型生成图片
- **Steps:**
  ```python
  generator = NanoBanana()
  prompt = "未来城市夜景"

  # GPT-image-2
  generator.generate(prompt, model="gpt-image-2", save_path="gpt.jpg")

  # Gemini
  generator.generate(prompt, model="gemini-3.1-flash-image-preview", save_path="gemini.jpg")

  # 集梦
  generator.generate(prompt, model="doubao-seedream-5-0-260128", save_path="seedream.jpg")
  ```
- **Expected output:** 三张不同风格的图片

### Example 3: 为文章生成封面图

- **Input:** 为微信公众号文章生成封面
- **Steps:**
  ```bash
  python ~/.claude/skills/nano-banana/scripts/nano_banana.py \
      "AI 技术改变世界" \
      --model gpt-image-2 \
      --size 16:9 \
      --quality high \
      --output article-cover.jpg
  ```
- **Expected output:** `article-cover.jpg`

## Configuration

### 环境变量

| 变量名 | 说明 |
|--------|------|
| `TU_ZI_API_KEY` | tu-zi.com API Key |

### 获取 API Key

1. 访问 [tu-zi.com](https://tu-zi.com/) 注册账号
2. 在 API 管理页面创建 API Key
3. 设置环境变量：
   ```bash
   # 临时设置（当前会话）
   export TU_ZI_API_KEY="your-api-key"

   # 永久设置（添加到 ~/.zshrc 或 ~/.bashrc）
   echo 'export TU_ZI_API_KEY="your-api-key"' >> ~/.zshrc
   source ~/.zshrc
   ```

## API Details

### 端点信息

| 参数 | 值 |
|------|-----|
| **API Host** | `api.tu-zi.com` |
| **Endpoint** | `POST /v1/images/generations` |
| **认证方式** | `Bearer Token` |

### 请求格式（通用）

```json
{
  "model": "gpt-image-2",
  "prompt": "画个海洋世界",
  "size": "1024x1024",
  "response_format": "url"
}
```

### 响应格式

```json
{
  "created": 1589478378,
  "data": [
    {
      "url": "https://..."
    }
  ]
}
```

## 命令行参数

```bash
usage: nano_banana.py [-h] [--output OUTPUT] [--model MODEL] [--size SIZE]
                      [--quality QUALITY] [--num NUM] [--style {vivid,natural}]
                      [--seed SEED] [--watermark WATERMARK]
                      [--guidance-scale GUIDANCE_SCALE] [--api-key API_KEY]
                      [--timeout TIMEOUT] [--list-models]
                      [prompt]

positional arguments:
  prompt                图片生成提示词

options:
  -h, --help            显示帮助信息
  --output OUTPUT, -o OUTPUT
                        输出文件路径 (默认: nano_banana_output.png)
  --model MODEL, -m MODEL
                        模型 ID (默认: gpt-image-2)
  --size SIZE, -s SIZE  图片尺寸（根据模型自动转换格式）
  --quality QUALITY, -q QUALITY
                        图片质量
  --num NUM, -n NUM     生成数量（仅 GPT-image-2 支持）
  --style {vivid,natural}
                        风格（仅 GPT-image-2 支持）
  --seed SEED           随机种子（仅 Seedream 支持）
  --watermark WATERMARK 是否加水印（仅 Seedream 支持）
  --guidance-scale GUIDANCE_SCALE
                        引导比例（仅 Seedream 支持）
  --api-key API_KEY, -k API_KEY
                        tu-zi.com API Key
  --timeout TIMEOUT     请求超时时间（秒，默认: 120）
  --list-models         列出所有支持的模型
```

## References

- tu-zi.com API 文档:
  - GPT-image: https://tuzi-api.apifox.cn/343646952e0
  - Gemini: https://tuzi-api.apifox.cn/343646956e0
  - 集梦: https://tuzi-api.apifox.cn/349741169e0
- `scripts/nano_banana.py`: 完整实现代码

## Maintenance

- Sources: tu-zi.com API 文档
- Last updated: 2026-05-30
- Known limits:
  - 需要网络连接调用 API
  - API Key 需要用户自行申请
  - 不同模型支持的参数不同