🤖 Gemini 3 Pro Image (API Fallback)

This is the node the whole pack is built around: a cloud image generator that calls Google's gemini-3-pro-image-preview model - the one Google markets as Nano Banana Pro - and drops the result back into ComfyUI as a normal IMAGE tensor. No checkpoints, no LoRAs, no VAE, no GPU. The model only exists on Google's servers, so if you want its 4K native output and text rendering next to your local nodes, this is the door.

That "API Fallback" in the name is the actual selling point, not marketing. Google's image API is famously temperamental at peak hours - 503 overloads, 429 rate limits, and IMAGE_OTHER blocks on prompts Google's filters don't like. This node treats those as the normal state of the world and engineers around them.

How it works

Under the hood it uses the official google-genai SDK, streaming generate_content_stream and converting the returned inline image data into a torch tensor. The interesting part is the resilience engine around that call:

• Up to 3 API keys, rotated round-robin. Each item in a batch starts on a different key so one exhausted key doesn't stall everything. The catch, spelled out in the README: rate limits apply per Google Cloud project, not per key - three keys from the same project share one quota. To actually triple your throughput, the three keys have to come from three separate projects.
• Smart backoff. 503s get exponential backoff with jitter (1s, 2s, 4s…), 429s trigger a 60-second cooldown to let the per-minute quota reset, 500s retry after 5–10 seconds, and if Google's error says "Please retry in 21s", the node parses that exact number and waits precisely that long.
• Stream integrity checks. If the connection drops mid-stream (that classic Windows WinError 10054), the node detects the missing STOP signal and retries with the next key instead of silently returning a truncated image.
• Looser safety filters. It sets all four harm categories to BLOCK_ONLY_HIGH, which kills a lot of the false-positive "content blocked" failures that plague creative prompts.
• Placeholder fallback. If every key and retry round fails, it returns a black placeholder plus an error string rather than killing your whole queue.

There's also a bypass toggle that replays the last successful generation for that node - handy for iterating on the rest of a workflow without spending another API call.

The credits twist

The use_comfyui_credits toggle defaults to ON. If you're logged into ComfyUI with a Comfy account token, the node tries to route through Comfy's own Gemini API node and spend your Comfy credits first; if that fails or you have no token, it silently falls back to your custom Google keys. Flip it off if you're paying Google directly and want your keys to be the primary path.

The fields that matter

• prompt - what to draw. Defaults to "Make this image cyberpunk style".
• model, aspect_ratio (12 options incl. auto), resolution (1K/2K/4K), seed - the standard creative controls.
• response_modalities - IMAGE+TEXT (default) returns the model's text alongside the image; IMAGE returns just pixels.
• api_key_1/2/3, api_max_retries (default 10), batch_delay (2.5s pacing between batch items).
• images (optional) - reference images for image-plus-prompt editing. The pack converts them to PNG parts and merges them with your prompt.

Outputs: processed_image (an IMAGE list - wire to Preview/Save) and text_response (a STRING list).

Installing it

ComfyUI Manager (search "ComfyUI-Gemini3-API-Fallback"), or:

cd ComfyUI/custom_nodes
git clone https://github.com/Latentnaut/ComfyUI-Gemini3-API-Fallback
python -m pip install google-genai pillow numpy requests

then restart. No model downloads. Then get a key from Google AI Studio and enable billing on the project - image models return Limit: 0 until you're on the pay-as-you-go tier.

Where people get burned

• Limit: 0 / 429 RESOURCE_EXHAUSTED - billing not enabled, or the project is still on the free tier. Enable billing, check the model's per-day quota in the Google Cloud Console, confirm the plan says "Pay-as-you-go".
• IMAGE_OTHER - Google's policy blocked the generation. Try a more generic prompt; the node's safety reconfiguration already reduces how often this bites.
• No keys but the credits toggle on - it falls back gracefully, but you'll see a warning in the console.
• "No API Key provided" placeholder - make sure at least one key field is filled (or credits are available).

One more honest note: this is a small, community-built pack (effectively zero Reddit footprint), not an official Comfy node. Every prompt and image leaves your machine for Google - that's the deal with any closed-model API node. For a well-engineered fallback path into Nano Banana, it's still one of the most complete options on the registry.