94 lines
6.0 KiB
Markdown
94 lines
6.0 KiB
Markdown
# 🚀 ComfyUI-Gemini3-API-Fallback
|
|
|
|
Expertly designed custom nodes for **Google Gemini** integration in ComfyUI, featuring a robust multi-key retry system to eliminate server errors and rate limits.
|
|
|
|
---
|
|
|
|
## 🌟 Key Features
|
|
|
|
### 🛡️ 3-Key Iterative System (API Fallback)
|
|
Stop worrying about "Server Error 500" or rate limits. These nodes allow you to input up to **3 different API keys**. If the primary key fails, the system automatically rotates to the next one and retries up to your configured `max_retries`.
|
|
|
|
### 🧠 Smart Retry & Dynamic Backoff
|
|
Featuring **Dynamic Delay Parsing**: If Google requests a specific wait time (e.g., *"Please retry in 21s"*), the node automatically reads this and respects the exact delay requested by the server, significantly increasing success rates during periods of high congestion.
|
|
- **Exponential Backoff (503)**: Progressively waits longer (1s, 2s, 4s...) with random jitter when models are overloaded, preventing server stampedes.
|
|
- **60s Quota Cooldown (429)**: Automatically pauses for 60 seconds when hitting rate limits to let your per-minute quota refresh.
|
|
- **Fast Internal Retry (500)**: Rapidly retries internal server errors with short 5-10s delays.
|
|
|
|
### 🛡️ Enhanced Safety Settings for Creative Freedom
|
|
Automatically configures Google's safety filters (Harassment, Hate Speech, Sexually Explicit, Dangerous Content) to `BLOCK_ONLY_HIGH`. This drastically reduces "Content Blocked" false positives for creative or professional prompts, avoiding frustrating `IMAGE_OTHER` formatting errors.
|
|
|
|
### 🛡️ Stream Integrity Verification
|
|
The nodes now strictly verify the completion of the response. If a connection is forcibly closed by the server or interrupted (e.g., *WinError 10054*), the system detects the missing "STOP" signal and automatically triggers a retry with key rotation, ensuring you never get truncated prompts or half-generated images.
|
|
|
|
### 🎨 Gemini 3 Pro Image (API Fallback)
|
|
Generate stunning high-fidelity images directly from ComfyUI using the latest `gemini-3-pro-image-preview` model.
|
|
- **Strict Model Separation**: Only image-native models are shown to avoid 404/400 errors.
|
|
- **Native Resolutions**: 1K, 2K, and 4K support.
|
|
- **Aspect Ratio Control**: Auto, 1:1, 16:9, 9:16, 21:9, and more.
|
|
- **Visual Success Indicators**: Now with `✅` icons and chunk counting in the console.
|
|
|
|
### 📝 Gemini 3 Pro (API Fallback)
|
|
The ultimate tool for prompt engineering, image analysis, and creative writing.
|
|
- **Native Batch Processing**: New `batch_count` parameter allows generating up to 64 unique prompts in a single node execution.
|
|
- **Versatile Models**: Includes `gemini-3-pro-preview`, `gemini-3-flash-preview` (lowest latency), `gemini-2.0-pro-exp`, and `gemini-2.0-flash`.
|
|
- **Iterative Logic**: Optimized for complex tasks with long-processing times.
|
|
- **Automatic Multi-Modal**: Handles text and images seamlessly for context-aware generation.
|
|
|
|
---
|
|
|
|
---
|
|
|
|
## 🔑 Crucial: Setting up your Google API Keys
|
|
|
|
To use **Gemini-3-Pro-Image** models, you **must** enable billing in your Google Cloud project and verify your quotas. Otherwise, you will encounter a `Limit: 0` error.
|
|
|
|
### ⚠️ Troubleshooting "Limit: 0" or "429 RESOURCE_EXHAUSTED"
|
|
If you get an error saying `limit: 0`, even with billing enabled:
|
|
1. **Model Quota**: Image models (`gemini-2.0-flash` or `imagen`) have a separate quota. Go to [Google Cloud Console > Quotas](https://console.cloud.google.com/iam-admin/quotas) and search for `generativelanguage.googleapis.com/generate_requests_per_model_per_day`.
|
|
2. **Project Tier**: Return to [Google AI Studio](https://aistudio.google.com/), go to **Settings > Plan**, and confirm your project is on the **"Pay-as-you-go"** plan. If it says "Free", click "Edit" and choose your Billing project.
|
|
3. **Region**: Some image models are only available in certain regions. Ensure your project is not restricted.
|
|
|
|
### 1. Get your API Keys
|
|
1. Go to [Google AI Studio](https://aistudio.google.com/).
|
|
2. Sign in with your Google Account.
|
|
3. Click on the **"Get API key"** button on the top left sidebar.
|
|
4. Click **"Create API key in new project"**.
|
|
5. Copy your API Key.
|
|
6. **IMPORTANT FOR 3x QUOTA**: Google applies Rate Limits (429) at the *Google Cloud Project* level, NOT per API key. If you generate 3 keys within the *same* project, they share the exact same quota. To genuinely triple your bandwidth and avoid 429 limits during heavy batches, your 3 API keys **must come from 3 separate Google Cloud Projects** with separate billing accounts enabled.
|
|
### 2. Enable Billing (Required for Image Generation)
|
|
By enabling billing, you move to the "Pay-as-you-go" tier which unlocks the quota for image models.
|
|
> **Note:** Google often provides $300 in free credits for new accounts, which covers a significant amount of usage.
|
|
|
|
1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
|
|
2. Select your project from the top dropdown.
|
|
3. Navigate to **Billing** in the sidebar menu.
|
|
4. Click **"Add billing account"** and enter your payment information.
|
|
5. **Link your project**: In the "Account Management" tab of the Billing section, ensure your project is linked to the new billing account.
|
|
6. **Set Budget Alerts (Highly Recommended)**: In the "Budgets & Alerts" menu, create a budget (e.g., $1 or $5) to receive email notifications and avoid unexpected charges.
|
|
|
|
### 3. Verify in AI Studio
|
|
Return to [Google AI Studio](https://aistudio.google.com/), go to **Settings/Plan**, and confirm your project is now on the **"Pay-as-you-go"** plan. This will replace the "Limit: 0" with a functional quota.
|
|
|
|
---
|
|
|
|
## 🛠️ Installation
|
|
|
|
1. Navigate to your ComfyUI `custom_nodes` folder.
|
|
2. Clone this repository:
|
|
```bash
|
|
git clone https://github.com/USER/ComfyUI-Gemini3-API-Fallback
|
|
```
|
|
3. Install dependencies:
|
|
```bash
|
|
python -m pip install google-genai pillow numpy torch
|
|
```
|
|
|
|
---
|
|
|
|
## ⚙️ Configurable Parameters
|
|
- `api_key_1, 2, 3`: Your iterative keys.
|
|
- `max_retries`: Number of full rotation rounds to attempt before giving up (Default: 10).
|
|
- `English Logging`: Real-time console feedback on key rotation and server wait times.
|
|
|
|
--- |