Liquid Postman (Gemini Image)

ComfyUI's whole identity is local: your GPU, your models, your weights. Liquid Postman (Gemini Image) is the polite opposite - a single node that hands your prompt to Google's Gemini API and pulls the finished image back down as a normal ComfyUI IMAGE tensor. No local checkpoint, no VRAM, no model download. The price is an API key, per-image billing, and Google's content filters, which you should read about before you fall in love with it.

The model behind the default gemini-3.1-flash-image-preview is what Google sells as Nano Banana 2 (Gemini 3.1 Flash, Feb 2026). The Nano Banana family is where people go for the things local models still fumble: legible text in images - signs, labels, posters - long literal multi-object prompts, and real-world objects that actually look like themselves. It's also genuinely censored: strict IMAGE_SAFETY filtering, no celebrities or IP, and every output carries an invisible SynthID watermark. If that's a dealbreaker, close the tab. If it fits the job, this is the cleanest way to run it from inside ComfyUI - and one of the few cloud generation nodes that's actually painless to install.

How it works

Nothing clever runs on your machine. The node POSTs to generativelanguage.googleapis.com/v1beta/models/{model}:generateContent with your key in the x-goog-api-key header, then parses the response. It builds the request's contents array from three places: your text prompt, any images you've wired into the images pin (uploaded through the Gemini Files API first - resumable upload, so there's genuinely no file size limit), and any .pdf/.docx paths in the files field (a folder path is scanned for those two types automatically).

responseModalities, aspectRatio, and imageSize go into generationConfig; the seed is only sent when it's 0 or above; search_grounding appends a google_search tool so the model can pull live info; and system_prompt becomes a system_instruction. The response's base64 image parts are decoded to PIL and stacked into a float tensor batch, with any text parts joined into the text output. That's the whole show - its real dependencies are just requests and Pillow.

The inputs that matter

• api_key - required, and the node hard-refuses to run without it. Grab one at aistudio.google.com/apikey.
• prompt - your actual prompt. Multiline, so be as long-winded as you like.
• model - a plain STRING, so you can type newer model names as Google ships them without waiting on the author.
• aspect_ratio and resolution - eight ratios from 1:1 to 21:9, and 1K/2K/4K.
• response_modalities - IMAGE or IMAGE+TEXT. The text output stays empty unless you pick IMAGE+TEXT.
• images (optional) - wire an existing tensor in for editing or reference. It gets re-uploaded to Google each run, so that's a round trip per image.

Outputs are image (IMAGE) and text (STRING). The image is already pixels - no VAE decode needed. Wire it straight into Save Image, an upscaler, or a training-dataset folder. That last one is the pattern that actually shows up in the community: generate a character sheet in Nano Banana, bring it into ComfyUI, upscale it, then feed it to a LoRA trainer. This node is the seam that makes that work without leaving the graph.

Installing it

ComfyUI Manager: search "Liquid Postman" and install. CLI: comfy node install comfyui-liquidpostman, or git clone https://github.com/majdsalim/ComfyUI-LiquidPostman.git into custom_nodes/ and pip install requests Pillow. It needs Python 3.12+, but there are no model downloads and nothing heavy - install is genuinely one-and-done, which is rarer than it should be.

Where people get burned

• The API key rides in your workflow JSON, and ComfyUI bakes workflow JSON into output PNGs. Save an image with the key still in the node, share it, and you've handed someone a live Gemini key. Blank the field (or use a capped key) before sharing anything.
• "Gemini returned no images" is the safety filter, not a bug. The built-in system prompt literally orders the model to always produce an image - Google's filters still win sometimes. Reword the prompt or flip to IMAGE+TEXT so you at least see the model's reasoning text.
• It costs real money. There's a free daily tier, then pay-as-you-go; a batch loop queuing hundreds of frames is how people meet their first surprise bill.
• seed is best-effort. It's passed through to the API, but don't expect local-sampler reproducibility - cloud models don't give you that.
• When something does go wrong, flip debug on: it prints the request body and response metadata to the console and makes diagnosis far easier.