# ComfyUI Nano Banana Node V3

A ComfyUI custom node for Google Vertex AI / Gemini image generation with **workflow-level parallel execution**. Multiple instances of this node run concurrently within a workflow, enabling faster batch processing.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![ComfyUI](https://img.shields.io/badge/ComfyUI-0.3.x+-blue.svg)](https://github.com/comfyanonymous/ComfyUI)

> **Note**: This is the V3 (parallel execution) version designed for ComfyUI 0.3.x+. For the legacy version with chat mode and multi-output nodes, see [ComfyUI-Nanobanana_node](https://github.com/darrell-goh/ComfyUI-NanoBanana_node).

## Features

- **Workflow-Level Parallel Execution** - Multiple nodes run concurrently using ComfyUI's V3 async execution engine
- **Dynamic Image Inputs** - 3 fixed image inputs always visible, with additional slots appearing dynamically as you connect images (up to 14 total)
- **Image Generation** - Generate images with Gemini models through Vertex AI with customizable resolution (1K/2K/4K) and aspect ratios
- **Auto Aspect Ratio Detection** - Automatically detects and matches aspect ratio from input images
- **Real-time Usage Metadata Display** - Shows processing time and token counts directly on the node UI
- **Thoughts Output** - Separate output for model reasoning/thinking content (for supported models)
- **Per-Instance Logging** - Execution logs saved to `logs/` directory in JSON Lines format

## Requirements

- **ComfyUI 0.3.x or later** (requires V3 node support via `comfy_api.latest`)
- Python 3.10+
- Valid Vertex AI API key or Nano Banana proxy endpoint

### Python Dependencies

```
aiohttp>=3.8.0
Pillow
python-dotenv
numpy
torch
```

## Installation

1. **Clone the repository** into your ComfyUI `custom_nodes/` folder:
   ```bash
   cd ComfyUI/custom_nodes
   git clone https://github.com/darrell-goh/ComfyUI-NanoBanana_APIv3_node.git
   ```

2. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

3. **Configure environment variables**:
   ```bash
   cp .env.template .env
   ```
   Edit `.env` with your API credentials (see [Configuration](#configuration) below).

4. **Restart ComfyUI**

## Configuration

Create a `.env` file in the node folder with your API credentials:

### Option 1: Nano Banana Proxy (Recommended)

```env
VERTEX_AI_API_KEY=your_api_key_here
VERTEX_AI_USE_SIMPLE_ENDPOINT=true
VERTEX_AI_ENDPOINT=https://your-nano-banana-endpoint.com
VERTEX_AI_MODELS=gemini-3-pro-image-preview,gemini-2.5-flash-image
```

### Option 2: Direct Vertex AI

```env
VERTEX_AI_API_KEY=your_vertex_ai_api_key
VERTEX_AI_USE_SIMPLE_ENDPOINT=false
VERTEX_AI_PROJECT=your-gcp-project-id
VERTEX_AI_LOCATION=us-central1
VERTEX_AI_MODELS=gemini-3-pro-image-preview,gemini-2.5-flash-image
```

## Node Reference

### Nano Banana (Pro) V3

The main node for interacting with Gemini models through Vertex AI.

#### Inputs

| Input | Type | Description |
|-------|------|-------------|
| **system_prompt** | STRING | System prompt that sets the behavior of the model |
| **user_message_box** | STRING | User message/prompt to send to the model |
| **model** | COMBO | Gemini model to use (configured via `VERTEX_AI_MODELS`) |
| **image_generation** | BOOLEAN | Enable image generation mode |
| **resolution** | COMBO | Output resolution: `1K`, `2K`, or `4K` |
| **aspect_ratio** | COMBO | Aspect ratio: `None`, `Auto`, `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `5:4`, `4:5`, `21:9` |
| **temperature** | FLOAT | Controls randomness (0.0 - 1.0) |
| **timeout** | INT | Request timeout in seconds (30-600, default: 300) |
| **image_1-3** | IMAGE | Fixed image inputs (always visible) |
| **image_4-14** | IMAGE | Dynamic image inputs (appear when fixed inputs are connected) |

#### Outputs

| Output | Type | Description |
|--------|------|-------------|
| **Text Output** | STRING | Text response from the model |
| **Image** | IMAGE | Generated image tensor (if image generation enabled) |
| **Stats** | STRING | Execution statistics (TPS, time, token count) |
| **Thoughts** | STRING | Model's reasoning/thinking content (if available) |

### On-Node Metadata Display

When execution completes, the node displays real-time statistics:

- **Aspect Ratio** (green) - Auto-detected aspect ratio (e.g., "Auto → 16:9")
- **Processing Time** (cyan) - Request duration in seconds
- **Output Tokens** (yellow) - Number of output tokens generated
- **Thinking Tokens** (magenta) - Reasoning tokens (for supported models)
- **Total Tokens** (yellow) - Total token count

## Parallel Execution

This node leverages ComfyUI's V3 async execution model. When multiple Nano Banana V3 nodes exist in a workflow without dependencies on each other, they execute **concurrently** rather than sequentially.

### Example

A workflow with 4 independent image generation nodes will run all 4 API calls in parallel:

```
┌─────────────┐     ┌─────────────┐
│ Load Image  │────▶│ NanoBanana  │──┐
└─────────────┘     │    V3 #1    │  │
                    └─────────────┘  │
┌─────────────┐     ┌─────────────┐  │    ┌─────────────┐
│ Load Image  │────▶│ NanoBanana  │──┼───▶│   Output    │
└─────────────┘     │    V3 #2    │  │    │   Gallery   │
                    └─────────────┘  │    └─────────────┘
┌─────────────┐     ┌─────────────┐  │
│ Load Image  │────▶│ NanoBanana  │──┘
└─────────────┘     │    V3 #3    │
                    └─────────────┘
```

All three NanoBanana nodes execute their API requests simultaneously, significantly reducing total workflow time.

## Logging

Execution logs are saved to the `logs/` directory in JSON Lines format:

```
logs/
├── node_1.log    # Logs for node ID 1
├── node_2.log    # Logs for node ID 2
└── ...
```

Each log entry contains:
- Timestamp
- Workflow run ID
- Node ID
- Model used
- Usage metadata (tokens, processing time)
- Prompt and response previews

## Troubleshooting

### Node not appearing in ComfyUI
- Ensure you're running ComfyUI 0.3.x or later (V3 node support required)
- Check the ComfyUI console for import errors
- Verify all dependencies are installed

### API errors
- Check that your `.env` file is properly configured
- Verify your API key is valid
- Ensure the endpoint URL is correct

### Metadata not displaying on node
- This feature requires ComfyUI's PromptServer (should be available by default)
- Check browser console for JavaScript errors

## Changelog

### v1.0.0
- Initial V3 release with parallel execution support
- Real-time usage metadata display on node UI
- Dynamic image inputs (up to 14 images)
- Auto aspect ratio detection
- Thoughts output for reasoning models
- Per-instance JSON logging
- Support for Gemini 3 Pro and Gemini 2.5 Flash models

## License

MIT License - see [LICENSE](LICENSE) file.

## Credits

- Built for use with [ComfyUI](https://github.com/comfyanonymous/ComfyUI)
- Powered by Google Vertex AI API