# NanoBanana

AI 图像生成工具，使用 **OpenAI 兼容协议**，支持任何兼容的图像生成服务。

## 特性

- 🎨 **文生图** - 根据文本描述生成图片
- 🖼️ **图生图** - 基于参考图片生成新图片
- 🔄 **多 Provider 兼容** - OpenRouter 等
- 📦 **双版本支持** - MCP Server + Clawdbot Plugin

## 版本选择

| 版本 | 适用场景 | 目录 |
|------|---------|------|
| **MCP Server** | Claude Desktop / Claude Code | `src/` |
| **Clawdbot Plugin** | Clawdbot AI 助手 | `clawdbot-plugin/` |

---

## MCP Server

用于 Claude Desktop 和 Claude Code。

### 快速使用

```bash
npx nanobanana-mcp
```

### 从源码安装

```bash
git clone https://github.com/superboolgithub/nanobanana-mcp.git
cd nanobanana-mcp
npm install
npm run build
```

### 环境变量

| 变量名 | 必填 | 说明 | 默认值 |
|--------|------|------|--------|
| `NANOBANANA_API_KEY` | ✅ | API 密钥 | - |
| `NANOBANANA_BASE_URL` | ✅ | API 基础 URL | - |
| `NANOBANANA_OUTPUT_DIR` | ✅ | 图片输出目录 | - |
| `NANOBANANA_DEFAULT_ASPECT_RATIO` | ❌ | 默认宽高比 | `1:1` |
| `NANOBANANA_DEFAULT_IMAGE_SIZE` | ❌ | 默认图片尺寸 | `1K` |
| `NANOBANANA_DEFAULT_MODEL` | ❌ | 默认模型 | `google/gemini-2.5-flash-image-preview` |

### Claude Desktop 配置

在 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "nanobanana": {
      "command": "npx",
      "args": ["-y", "nanobanana-mcp"],
      "env": {
        "NANOBANANA_API_KEY": "your-api-key",
        "NANOBANANA_BASE_URL": "https://openrouter.ai/api",
        "NANOBANANA_OUTPUT_DIR": "/path/to/output"
      }
    }
  }
}
```

### Claude Code 配置

在 `~/.claude.json` 中添加：

```json
{
  "mcpServers": {
    "nanobanana": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "nanobanana-mcp"],
      "env": {
        "NANOBANANA_API_KEY": "your-api-key",
        "NANOBANANA_BASE_URL": "https://openrouter.ai/api",
        "NANOBANANA_OUTPUT_DIR": "/path/to/output"
      }
    }
  }
}
```

---

## Clawdbot Plugin

用于 [Clawdbot](https://github.com/clawdbot/clawdbot) AI 助手。

### 安装

```bash
cp -r clawdbot-plugin ~/.clawdbot/extensions/nanobanana
```

### 配置

在 `~/.clawdbot/clawdbot.json` 中添加：

```json
{
  "plugins": {
    "entries": {
      "nanobanana": {
        "enabled": true,
        "config": {
          "apiKey": "your-api-key",
          "baseUrl": "https://openrouter.ai/api",
          "outputDir": "/tmp/nanobanana",
          "defaultAspectRatio": "1:1",
          "defaultImageSize": "1K",
          "defaultModel": "google/gemini-2.5-flash-image-preview"
        }
      }
    }
  }
}
```

### 配置项

| 配置项 | 必填 | 说明 | 默认值 |
|--------|------|------|--------|
| `apiKey` | ✅ | API 密钥 | - |
| `baseUrl` | ✅ | API 基础 URL | - |
| `outputDir` | ❌ | 图片输出目录 | `/tmp/nanobanana` |
| `defaultAspectRatio` | ❌ | 默认宽高比 | `1:1` |
| `defaultImageSize` | ❌ | 默认图片尺寸 | `1K` |
| `defaultModel` | ❌ | 默认模型 | `google/gemini-2.5-flash-image-preview` |

---

## 工具说明

### generate_image - 文生图

根据文本描述生成图片。

**参数：**
- `prompt` (必填) - 图片描述，最大 5000 字符
- `aspectRatio` - 宽高比
- `imageSize` - 图片尺寸
- `model` - 模型名称

### edit_image - 图生图

基于参考图片生成新图片。

**参数：**
- `prompt` (必填) - 图片描述
- `referenceImageUrl` (必填) - 参考图片 URL
- `aspectRatio` - 宽高比
- `imageSize` - 图片尺寸
- `model` - 模型名称

---

## 参数选项

### 宽高比 (aspectRatio)

| 值 | 分辨率 | 说明 |
|----|--------|------|
| `1:1` | 1024×1024 | 方形（默认） |
| `16:9` | 1344×768 | 横版宽屏 |
| `9:16` | 768×1344 | 竖版 |
| `4:3` | 1184×864 | 横版 |
| `3:4` | 864×1184 | 竖版 |
| `2:3` | 832×1248 | 竖版 |
| `3:2` | 1248×832 | 横版 |
| `4:5` | 896×1152 | 竖版 |
| `5:4` | 1152×896 | 横版 |
| `21:9` | 1536×672 | 超宽屏 |

### 图片尺寸 (imageSize)

| 值 | 说明 |
|----|------|
| `1K` | 标准分辨率（默认） |
| `2K` | 高分辨率 |
| `4K` | 最高分辨率 |

### 兼容模型

- `google/gemini-2.5-flash-image-preview` - 快速生成
- `google/gemini-3-pro-image-preview` - 高质量
- `gemini-2.5-flash-image` - Gemini Flash
- `black-forest-labs/flux.2-pro` - Flux Pro
- 其他支持图像生成的模型

---

## API 协议

使用 **OpenAI Chat Completions API** 格式：

### 请求

```http
POST /v1/chat/completions
Content-Type: application/json
Authorization: Bearer <api-key>

{
  "model": "gemini-2.5-flash-image",
  "messages": [
    { "role": "user", "content": "Generate a beautiful sunset" }
  ],
  "modalities": ["image", "text"],
  "image_config": {
    "aspect_ratio": "16:9",
    "image_size": "2K"
  }
}
```

### 响应格式

支持两种响应格式：

**格式 1：OpenRouter 风格**
```json
{
  "choices": [{
    "message": {
      "content": "Here's your image",
      "images": [{
        "image_url": { "url": "data:image/png;base64,..." }
      }]
    }
  }]
}
```

**格式 2：Markdown 内嵌**
```json
{
  "choices": [{
    "message": {
      "content": "![image](data:image/png;base64,...)"
    }
  }]
}
```

---

## 兼容的 Provider

任何使用 OpenAI Chat Completions API 格式的图像生成服务：

- [OpenRouter](https://openrouter.ai)
- 其他 OpenAI 兼容 API

---

## 使用示例

```
"生成一张可爱的猫咪图片"
"生成一张 4K 横版的日落海滩风景"
"基于这张图片，生成一个卡通风格的版本"
```

---

## 开发

```bash
# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 运行
npm start
```

---

## License

MIT