ComfyUI_Gemini

🍌 ComfyUI Gemini Nodes Suite

A suite of ComfyUI custom nodes built around Google's Gemini API — image generation ("Nano Banana"), spatial understanding (object detection & segmentation) — plus a set of fast, local (no-API) utility nodes for working with images and masks.

✨ Features

• Text-to-Image Generation: Create high-quality images from text descriptions
• Image Editing: Modify existing images using natural language instructions
• Style Transfer: Apply styles from one image to another
• Multi-Image Composition: Blend multiple images together
• Spatial Understanding: Object detection (bounding boxes) and segmentation (masks)
• Local Mask / Image Utilities: Selecting, separating, diffing, and auto-cropping — all run locally, no API call
• Environment Variable Support: Secure API key management via .env files
• Batch Generation: Generate up to 4 image variations at once
• Safety Controls: Configurable content safety settings
• Comprehensive Error Handling: Detailed error messages and fallbacks

🧩 Nodes in this Pack

Gemini API nodes (require a Google API key)

| Node | What it does | |------|--------------| | 🍌 Nano Banana (Gemini Image Gen) | Text-to-image and image editing with Gemini 2.5 Flash Image | | 🔍 Object Detection | Detects objects and returns bounding boxes | | 🎭 Segmentation | Produces precise object masks | | ✨ Batch Refine | Gemini Pro batch detail-refinement |

Local utility nodes (no API call, run instantly)

| Node | Inputs → Outputs | What it does | |------|------------------|--------------| | 🎭 Mask Stitch | image + refined + mask → composited | Composites a refined region back onto an original at a mask location (feather, color-match) | | 🧰 Mask Tools | mask → mask | Assorted mask post-processing helpers | | 🔢 Image Select | images (batch) + index → image, mask | Pick one image out of a batch by index (image 0, image 1, …). Normalizes odd tensor layouts | | 🎚️ Mask Select | masks (batch) + index → mask, preview | Pick one mask out of a batch by index — MASK counterpart of Image Select | | 🧩 Separate Mask Components | mask → masks (one per blob), preview, count | Splits a mask into its individual connected blobs (fast scipy labeling), with area filtering and sorting | | ✏️ Draw Diff Mask | clean_image + drawn_image → mask, strokes, preview | Compares a clean image with a drawn-on copy and returns the drawn area as a mask (any pen color; fills enclosed shapes) | | ✂️ Garment Auto Crop | image → cropped_image, mask, x, y, w, h | Auto-crops the empty backdrop around a garment. Handles dark frames, color-matching charts, and light-on-light garments | | 🔢 Select Image From List | images (list) + index → selected_image, selected_index, count | Pick one image out of an image list by index, keeping its native dimensions. List-aware replacement for batch selectors when images have mixed sizes | | 🧺 List → Batch (Padded) | images (list) → batch, width, height, count | Stacks a mixed-size image list into a real batch without scaling — pastes each image onto a max-size canvas (pad instead of resize) | | 🧺 List Passthrough (keep dims) | images (list) → images (list), count | Flattens the input into a clean image list, emitted as a list so each image keeps its own dimensions |

💡 The local utility nodes all live under the AI/Image Analysis/Google category in the node menu.

ℹ️ List vs. batch: a ComfyUI IMAGE batch is one [B, H, W, C] tensor, so every image in it must share the same H×W. If your images have different sizes, you can either keep them a list (native sizes preserved — use Select Image From List) or force a batch (uniform size — List → Batch (Padded) pads instead of distorting).

📋 Requirements

• ComfyUI (latest version recommended)
• Python 3.8+
• Google API Key with Gemini API access (only for the Gemini API nodes)
• scipy — required by the Separate Mask Components and Garment Auto Crop nodes for fast connected-component labeling and hole-filling. Install with pip install scipy. (Without it those two nodes fall back to a slower/cruder path.)

🚀 Installation

Step 1: Install the Node

1. Navigate to your ComfyUI custom nodes directory:

cd ComfyUI/custom_nodes/

2. Create a new folder for the node:

mkdir ComfyUI_Gemini
cd ComfyUI_Gemini

3. Copy the pack files into this directory:

• __init__.py
• all gemini_*.py node files
• requirements.txt
• .env.example (optional but recommended)

Don't copy the dev/test folders (e.g. image_example/, __pycache__/) — they aren't part of the node and can be large.

Step 2: Install Dependencies

Install the required Python packages:

pip install -r requirements.txt

Important: Make sure to install google-genai (NOT google-generativeai):

pip install google-genai python-dotenv Pillow

Step 3: Set Up Your API Key (Secure Method)

🔒 RECOMMENDED: Use .env file for security

You have three options for providing your Google API key:

Option 1: Using a .env file (Recommended - Most Secure) ✅

1. Copy .env.example to .env:

cp .env.example .env

2. Edit .env and add your API key:

GOOGLE_API_KEY=your-actual-api-key-here

3. Leave the API key field empty in ComfyUI nodes
   • The node will automatically load from .env
   • Your workflows won't contain the API key
   • Safe to share workflows

Security Note: The .env file is already in .gitignore to prevent accidentally committing your API key.

Option 2: System Environment Variable

Set the environment variable in your system:

Linux/Mac:

export GOOGLE_API_KEY="your-actual-api-key-here"

Windows (Command Prompt):

set GOOGLE_API_KEY=your-actual-api-key-here

Windows (PowerShell):

$env:GOOGLE_API_KEY="your-actual-api-key-here"

Option 3: Direct Input in ComfyUI

Enter your API key directly in the node's input field (less secure, not recommended for shared workflows).

Step 4: Get Your Google API Key

1. Visit Google AI Studio
2. Sign in with your Google account
3. Click "Get API Key"
4. Create a new API key or use an existing one
5. Copy the key and save it securely

🎨 Usage

Basic Text-to-Image Generation

1. Add the "🍌 Nano Banana (Gemini Image Gen)" node to your workflow
2. Connect the API key (or use environment variable)
3. Enter your prompt describing the image you want
4. Select the desired image size/aspect ratio
5. Click "Queue Prompt" to generate

Image Editing

1. Connect an input image to the image_for_editing input
2. Write an editing instruction in the prompt (e.g., "change the background to a sunset")
3. The model will modify the image based on your instructions

Advanced Settings

• Temperature: Controls creativity (0.0 = consistent, 2.0 = highly creative)
• Seed: Use -1 for random, or set a specific value for reproducible results
• Enhance Prompt: Automatically improves your prompt for better results
• Negative Prompt: Describe what you don't want in the image
• System Prompt: Add custom instructions to guide the model's behavior
• Safety Settings: Control content filtering levels

Local Utility Nodes

These need no API key and run instantly.

🔢 Image Select / 🎚️ Mask Select — feed in a batch and an index to pull out one item (index 0 = first). out_of_range chooses clamp (return the last) or wrap. Both report the real batch_size so you can wire it to the index range.

🧩 Separate Mask Components — splits a mask with several disconnected white blobs into a batch of individual masks (one per blob). Useful with Image/Mask Select to grab a specific blob. Controls: threshold, connectivity (8 = diagonals merge, 4 = not), min_area (drop speckle), max_components, and sort_by (e.g. area_desc).

✏️ Draw Diff Mask — give it the clean_image and a drawn_image (the same picture with a shape scribbled on it in any color). It returns the drawn region as a mask. Key controls: threshold (sensitivity), fill_region (outline → solid), and close_gaps (bridge breaks in a hand-drawn outline so it still fills).

✂️ Garment Auto Crop — removes the empty backdrop around a garment. Defaults work for the vast majority of studio product shots — just plug it in. It automatically:

• estimates the backdrop color from the image border and flood-fills it away,
• ignores dark edge frames / vignettes,
• ignores a color-matching chart or hang tags (objects much smaller than the garment),
• retries at a lower tolerance when a garment is low-contrast (light-on-light).

Detection runs on a downscaled copy, so it's fast even on 8000+ px images, and the crop is applied at full resolution. Tuning knobs (rarely needed):

| Param | Default | Turn it… | |-------|---------|----------| | bg_tolerance | 0.09 | Lower if backdrop texture leaks in; the node auto-lowers it for light garments | | padding | 0.02 | Up for more margin around the garment | | ignore_border_objects | True | Keep on to strip dark backdrop frames | | min_object_size | 0.10 | Up to drop a larger stray object (chart/tag); 0 to keep every piece | | min_coverage | 0.01 | Safety net — returns the image uncropped if detection finds almost nothing |

Outputs cropped_image, the garment mask, and the crop box x, y, width, height (so you can apply the same crop elsewhere). Note: if a color chart sits inside a wide garment's bounding box, a rectangular crop can't remove it — the mask still excludes it.

🔧 Troubleshooting

Common Issues and Solutions

Error: "module 'google.generativeai.types' has no attribute 'DataLossError'"

Solution: You have the wrong library installed. Uninstall google-generativeai and install google-genai:

pip uninstall google-generativeai
pip install google-genai

Error: "Google API Key is missing"

Solution: Make sure your API key is properly set via one of the three methods described above.

Error: "Failed to initialize Google Gen AI client"

Solution: Verify your API key is valid and has access to the Gemini API.

No image generated / Safety blocking

Solution: Your prompt may have triggered safety filters. Try:

• Adjusting the safety settings to be less restrictive
• Rephrasing your prompt to be more appropriate
• Using different wording or being more specific

ImportError: No module named 'google'

Solution: Install the required package:

pip install google-genai

📝 Best Practices (Nano Banana)

These tips apply to the 🍌 Nano Banana image-generation node.

Writing Effective Prompts

1. Be Descriptive: Instead of "a cat", try "a fluffy orange tabby cat sitting on a windowsill"
2. Include Style: Add artistic style descriptions like "photorealistic", "oil painting", "3D render"
3. Specify Lighting: Mention lighting conditions like "golden hour", "studio lighting", "dramatic shadows"
4. Add Context: Include background and environment details
5. Use Photography Terms: For realistic images, use terms like "85mm lens", "shallow depth of field", "bokeh"

Example Prompts

Photorealistic:

A photorealistic portrait of an elderly Japanese ceramicist with deep wrinkles and a warm smile, carefully inspecting a glazed tea bowl in his sun-drenched workshop. Golden hour lighting, 85mm lens, shallow depth of field.

Artistic:

An impressionist painting of a lavender field in Provence at sunset, with vibrant purple hues and loose brushstrokes capturing the movement of the flowers in the breeze.

Fantasy:

A mystical floating island with a crystal castle, surrounded by waterfalls that cascade into clouds below, bioluminescent plants glowing in twilight, fantasy art style.

🔄 Updates and Versions

See CHANGELOG.md for the full, dated history.

Version 2.6.0 (Current) — List/batch helpers

• NEW: 🔢 Select Image From List — pick one image from an image list by index, keeping its native dimensions (list-aware replacement for batch selectors on mixed-size images)
• NEW: 🧺 List → Batch (Padded) — stack a mixed-size list into a real batch by padding (no scaling/distortion), with center/top-left alignment
• NEW: 🧺 List Passthrough (keep dims) — re-emit a list as a list so each image keeps its size
• No new dependencies

Version 2.5.0 — Local utility nodes

• NEW: 🔢 Image Select — pick one image from a batch by index
• NEW: 🎚️ Mask Select — pick one mask from a batch by index
• NEW: 🧩 Separate Mask Components — split a mask into its connected blobs
• NEW: ✏️ Draw Diff Mask — turn a drawn-on shape into a mask by diffing two images
• NEW: ✂️ Garment Auto Crop — auto-crop the backdrop around a garment (handles dark frames, color-matching charts, and light-on-light garments)
• Adds a scipy dependency for the two mask/crop nodes

Version 2.1.0 (With Auto-Fix)

• NEW: Automatic library conflict resolution
• Auto-detects and removes conflicting google-generativeai library
• Auto-installs correct google-genai library
• Self-healing installation for remote machines
• Emergency fix scripts included

Version 2.0.0

• Complete rewrite using the correct google-genai library
• Added dotenv support for secure API key management
• Improved error handling and user feedback
• Support for multiple image generation
• Enhanced prompt preparation
• Better safety settings configuration

📚 Additional Resources

• Google AI Studio - Get your API key and test prompts
• Gemini API Documentation - Official API docs
• Gemini 2.5 Flash Image Preview - Model announcement

🐛 Known Limitations

Nano Banana (image generation):

• Maximum 4 images per generation batch
• Image sizes are predefined (custom sizes limited to preset options)
• Some prompts may be blocked by safety filters
• The model is in preview and may have occasional availability issues

Garment Auto Crop:

• Tuned for garments on a fairly uniform, light studio backdrop
• A color-matching chart that sits inside a wide garment's bounding box can't be removed by a rectangular crop (the garment mask still excludes it)

📄 License

Released under the MIT License. Please also respect Google's terms of service and usage policies when using the Gemini API.

🤝 Support

If you encounter issues:

1. Check the troubleshooting section above
2. Ensure you're using the latest version of the node
3. Verify your API key has proper permissions
4. Check the ComfyUI console for detailed error messages

⚠️ Important Notes

• API Costs: The Gemini API may incur costs. Check Google's pricing
• Rate Limits: Be aware of API rate limits to avoid service interruptions
• Content Policy: Follow Google's content policy and guidelines
• API Key Security: Never share your API key publicly or commit it to version control