darrell-goh-ComfyUI-NanoBanana_APIv3_node/README.md

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.

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.

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:

   cd ComfyUI/custom_nodes
   git clone https://github.com/darrell-goh/ComfyUI-NanoBanana_APIv3_node.git
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure environment variables:

   cp .env.template .env
   

   Edit .env with your API credentials (see Configuration below).

4. Restart ComfyUI

Configuration

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

Option 1: Nano Banana Proxy (Recommended)

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

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 file.

Credits

• Built for use with ComfyUI
• Powered by Google Vertex AI API