199 lines
7.3 KiB
Markdown
199 lines
7.3 KiB
Markdown
# 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.
|
|
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](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
|