ComfyUI-OpenRouterImage

This is the node you wire in when you want Google's Gemini image models - Nano Banana Pro, the 3.1 Flash, the 2.5 Flash - sitting inside a ComfyUI workflow like any other generator. There are no weights to download, no VRAM involved, and no diffusion happening on your machine. You type a prompt, the node phones a cloud API, and an image tensor comes back that you can feed straight into an upscaler or a face fixer. It's the "the model doesn't run here" pattern, and for Gemini that's the only door: these models are closed, so local is not an option at any GPU size.

What makes this node different from ComfyUI's own official API nodes is the middleman. Instead of prepaid Comfy credits, it talks to OpenRouter - one key, one endpoint, and access to the whole Gemini image family (plus a free-tier routing of the 2.5 Flash that some people use as a cheap draft stage). It's a reseller path in a crowded market, which mainly matters for cost, region, and billing: one key at openrouter.ai and you're done, no Google Cloud project.

How it works

Read the source and it's not mysterious. The node uses the OpenAI Python SDK pointed at https://openrouter.ai/api/v1 and calls chat.completions.create with an extra_body that asks for image and text modalities plus an image_config carrying your resolution and aspect ratio. Reference images aren't uploaded - they're base64-encoded as JPEG data URLs and dropped into the user message as image_url parts, so a 10-image reference stack is really just one big request body. The model replies with a data:image URL, the node decodes it back into a PIL image, and that becomes the image output tensor.

The inputs that matter

Only five required fields, and you'll touch three of them most runs:

• user_prompt - what to draw. This is the text the model actually conditions on.
• model - google/gemini-3-pro-image-preview (the flagship, "Nano Banana Pro"), google/gemini-3.1-flash-image-preview, or google/gemini-2.5-flash-image. Pro is the quality pick; 3.1 Flash is the fast iteration pick.
• resolution and aspect_ratio - 0.5K/1K/2K/4K by 7 ratios. The catch: 0.5K is only valid on the 3.1 Flash; the node refuses it on anything else and hands you an error string instead of an image.

system_prompt is there if you want a role ("you are a product photographer…"), and image1–image10 are optional reference images for img2img-style steering. Outputs are image (the IMAGE tensor - wire it to Preview/Save) and status (a STRING that tells you what actually happened, which you'll learn to read).

Install

ComfyUI Manager, search OpenRouterImage, install, restart. Or:

cd ComfyUI/custom_nodes
git clone https://github.com/zuojianghua/ComfyUI-OpenRouterImage.git
cd ComfyUI-OpenRouterImage
pip install -r requirements.txt

Dependencies are light - openai, python-dotenv, pillow, requests. No model files, ever.

The gotcha the README gets wrong

The README tells you to "enter your API key in the api_key field." There is no api_key field in the shipped node. The code reads credentials from a .env file inside the custom node folder, via python-dotenv. That file is gitignored, so nothing leaks into version control, but you have to create it:

cd ComfyUI/custom_nodes/ComfyUI-OpenRouterImage
echo 'OPENROUTER_BASE_URL=https://openrouter.ai/api/v1' > .env
echo 'OPENROUTER_API_KEY=sk-or-...' >> .env

Restart ComfyUI after creating it. If you skip this step, every run just returns a small black image plus status: Error: OpenRouter API key is required - which is the node's placeholder behavior, not a render failure.

The other thing to know before you build a workflow around this: your prompt and reference images are leaving the machine, every call costs money, and the model enforces Google's content policy with an invisible SynthID watermark baked into every output. None of that is a bug - it's the price of running a model you were never allowed to download.