Gemini Prompt Expander 🪄

The Gemini Prompt Expander is the "AI" half of the ComfyUI-Merlin pack, and the name is only a little bit of a lie. It doesn't run anything locally - it takes your short prompt, phones home to Google's Gemini API, and returns a rewritten, sectioned version that reads like a casting call written by a photographer. "A woman as cinderella" becomes a structured block with Type, Subject, Outfit, Pose & Scene, Extra Details, Background, and Technical Details, all under 150 words. If you've ever stared at a blank prompt box, that's the pitch.

Is it worth it? Depends on how you feel about sending your prompts to a Google API and paying per call. The output is genuinely useful for one reason: block-structured prompts are exactly what modern LLM-encoded models want. The 2026 prompting research is pretty unanimous that separating subject, scene, and technical details into clear blocks beats a comma soup, and this node does that formatting for you. The catch is that it doesn't know what checkpoint you're feeding. If you're on SDXL or Illustrious, a sectioned paragraph is the wrong shape - those CLIP encoders want tags. Treat the expander as a tool for Flux-family, Z-Image, and other sentence-driven models.

How it works

Under the hood it uses Google's google-generativeai SDK, hardcoded to the gemini-1.5-flash model with a temperature of 1 and a 150-token output cap. It stuffs your text into a prompt template that demands the exact seven-section format, sends it to Gemini, and returns the reply as a STRING. Two extras worth knowing: it's marked as an output node, and the pack's JavaScript adds a read-only "Final Prompt" widget on the node itself, so you can eyeball the result without hunting for a preview node.

Inputs, outputs, and the API key situation

There are exactly two inputs. input_text is required - that's your starting prompt. api_key is optional but practically mandatory the first time, unless you've already set the GEMINI_API_KEY environment variable. The single output is a STRING with the expanded prompt, which wires into a CLIP Text Encode's positive input just like any prompt text.

The key handling is where this node gets opinionated, and you should know what you're signing up for. Type a key into the widget and it doesn't just use it - it persists it. On Windows it runs setx to store it as a system environment variable; on macOS/Linux it appends export GEMINI_API_KEY="..." to your ~/.bashrc. So your key ends up sitting in plaintext on disk. That's convenient once and mildly alarming always. The safer move is exporting GEMINI_API_KEY yourself and never touching the widget.

Installing it

Same pack install as the Magic Photo Prompter: ComfyUI Manager (search "ComfyUI-Merlin") or by hand:

cd ComfyUI/custom_nodes
git clone https://github.com/Xclbr7/ComfyUI-Merlin.git

Then restart. One thing to watch: the pack's __init__.py tries to pip install google-generativeai automatically on startup if the SDK isn't found. That auto-install is handy right up until it isn't - on a portable ComfyUI install it can hit the wrong Python and fail silently, leaving you with an import error on the node. If you see that, pip install google-generativeai into your ComfyUI environment manually and restart.

Troubleshooting

The most common failure is the node refusing with No API key provided. Please enter an API key or set the GEMINI_API_KEY environment variable. That's self-explanatory - export the variable and restart, or fill the widget.

Second, this is a live network call, so it needs internet, and a failed call fails the whole workflow. The node also forces execution on every run (it reports itself as always changed), so each queue pass costs you another Gemini call. The bill is trivial - 150 tokens per call - but it's a per-run cost on a remote API, and the reply can vary run to run.

And the one I'd flag first if things start failing: the model name gemini-1.5-flash is hardcoded in gemini_prompt_expander.py, and it's a 2024-era model name. Google has been retiring the older 1.5 lineup, so if you start getting model-not-found style errors, that's the first suspect - open the file, swap in a current model name like gemini-2.0-flash, and restart. It's one line, and it's the only real maintenance this node will ever ask of you.