ComfyUI-Gemini3

ComfyUI Gemini 3 Pro Node

A custom node for ComfyUI that integrates Google's cutting-edge Gemini 3 Pro model (specifically gemini-3-pro-image-preview) for native image generation and processing. This node is engineered for high-demand production workflows, featuring built-in multi-key load balancing, auto-retry mechanisms, and direct binary image handling.

🚀 Features

• Native Image Support: Uses the latest gemini-3-pro-image-preview model to receive direct binary image data. No unstable Base64 text decoding required.
• Multi-API Key Load Balancing: Supports up to 3 API Keys (api_key_1, api_key_2, api_key_3). If your primary key hits a rate limit, the node automatically switches to the next available key without stopping the workflow.
• Smart Auto-Retry System: If all keys are exhausted (Error 429), the node intelligently pauses for 15 seconds and retries the entire sequence automatically (up to 10 times). This ensures your long batch renders don't crash overnight.
• Stream Handling: Efficiently processes the streaming response from Google GenAI to capture both high-quality image and text outputs simultaneously.

📦 Installation

Manual Installation (Recommended)

1. Navigate to your ComfyUI custom_nodes directory via terminal/command prompt:

cd ComfyUI/custom_nodes/

2. Clone this repository:

git clone https://github.com/Daohoi123/ComfyUI-Gemini3.git

3. Install the required Python dependencies:

Navigate to ComfyUI-Gemini3

cd ComfyUI-Gemini3

Install the dependencies from requirements.txt

..\\..\\..\\python_embeded\python.exe -m pip install -r requirements.txt

(Note: This node requires the official google-genai library).

🛠️ Usage

1. Add the Node:

• Right-click in the ComfyUI workflow canvas.
• Navigate to: Gemini AI -> Gemini 3 Pro. <img width="639" height="495" alt="image" src="https://github.com/user-attachments/assets/8d2e4d48-764e-4c7d-951a-92e244a8c389" />

2. Connect Inputs:

• image: Connect an image source (e.g., Load Image, VAE Decode).
• api_key_1: Enter your primary Google Gemini API Key (Required).
• api_key_2 / api_key_3: (Optional) Enter backup keys here. The node will use these if Key 1 hits a limit.
• prompt: Enter your text instruction (e.g., "Transform this sketch into a realistic cyberpunk city"). 3. Outputs:
• processed_image: The resulting image generated by Gemini. Connect this to Save Image or Preview Image.
• text_response: The accompanying text description returned by the model (if any).

📋 Requirements

• ComfyUI (Latest version recommended)
• Python 3.10+
• Libraries:
  • google-genai
  • pillow
  • numpy

❓ Troubleshooting

Error 429 (Resource Exhausted)

Don't panic! This is normal behavior for free-tier API keys.Solution: The node handles this automatically. It will cycle through your provided keys. If all keys are exhausted, it will wait 15 seconds and try again. It will repeat this process up to 10 times before finally stopping.

ImportError: No module named 'google'

Solution: You haven't installed the dependencies yet. Please run the pip install command mentioned in the Installation section..

Model not found / 404

Solution: Ensure your API Key has access to the gemini-3-pro-image-preview model. This is often a preview model that requires specific access rights in Google AI Studio.

📜 License

This project is open-source and available under the MIT License.