Gemini Prompt Refiner

Every diffusion user hits the same wall: you know the vibe you want, but the words that make SDXL or Flux actually produce it are a different language. The Prompt Refiner is the node that sits upstream of your sampler and fixes that. You feed it "a dragon," and it returns a dense, structured, image-generator-ready prompt - lighting, composition, materials, mood - the way a prompt engineer would write it. Then you wire that output into your CLIP Text Encode and never write a detailed prompt by hand again.

This is the single most popular category of LLM-in-ComfyUI node (the KB's llm-in-comfyui.md calls prompt enhancement "routine"), and the honest take is: it works, with a caveat. Gemini is a closed API model, so it's excellent at this job but you're paying per refinement and sending your ideas off-machine. The local-LLM purists would rather run an 8B model on their own card for the same job - but if you want frontier-chat quality of prompt expansion and you don't mind the API, this node is the cleanest way to get it.

How it works

It's a generate_content call with a carefully-built system instruction baked in: "You are a world-class Prompt Engineer. Take a user's base concept and expand it into a highly detailed, professional prompt for an AI Image Generator." Crucially, the instruction ends with a hard stop - "Output ONLY the final refined prompt text. Do not include introductory or concluding conversational text." - which is the difference between a usable output and a paragraph of chat scaffolding that poisons your conditioning. The response comes back as a clean STRING.

Inputs and outputs that matter

• base_prompt - your rough idea. The only thing you must type.
• model - defaults to gemini-2.5-pro, a strong choice for this. 35 options if you want something lighter (Flash is faster and cheaper for throwaway iterations).
• system_instruction - the override knob. Leave empty for the default behavior; fill it to steer the refinement style ("expand with cinematic film terms", "keep it under 50 words", "focus on character detail").
• thinking_level - NONE/LOW/NORMAL/HIGH. The default NONE keeps it fast; bump it when you want the model to reason harder about composition before writing.
• temperature - 0.7 default. Lower for consistent, reproducible expansions; higher for variety when you're hunting for a take you like.

One output: refined_prompt (STRING). It goes into a CLIP Text Encode or wherever prompts enter your pipeline.

How to install it

Pack-level, like the rest of the Gemini set:

cd ComfyUI/custom_nodes
git clone https://github.com/IxMxAMAR/ComfyUI-API-Toolkit
cd ComfyUI-API-Toolkit
pip install -r requirements.txt

or "API Toolkit" in ComfyUI Manager. Needs google-genai>=0.8.0 and a Gemini API key (node field or GEMINI_API_KEY env var).

Common issues

The big one: don't paste the raw output into a model that wants booru-style tags (Illustrious, Pony, NoobAI bases). Gemini writes natural-language, cinematic prose - that's ideal for Flux and SDXL, wrong for tag-trained anime bases. If that's your base, use system_instruction to force a tag-list format instead.

Also worth knowing: because the model is instructed to output only the prompt, a blank refined_prompt usually means the API call failed or got filtered - check the console, and remember the pack's API nodes all re-run every queue, so each refinement is a paid call. Iterate on the base prompt thoughtfully rather than spamming Queue.