Face Swap Prompt Builder

Every NanoBanana FaceSwap node costs real money per call, and the thing it sends is a carefully constructed prompt that's deliberately engineered to not trip Gemini's safety classifier. FaceSwapPromptBuilder is the pack's free preview: it shows you exactly what text the swap nodes will build, with zero API calls and zero quota burned.

If you've ever watched a swap come back REFUSED and wondered what did it actually send, this node is the answer to that question. Wire it up, read the output, adjust your custom_hint, and only then queue the expensive node.

How it works

The prompt templates live in the pack's faceswap/prompts.py, and they're opinionated in a specific way: they avoid vocabulary that raises Gemini's safety-classifier sensitivity. No "swap", no "replace face", no "deepfake", no "fake". Instead: "edit", "redraw", "match identity", "render". The builder mirrors those templates exactly - same phrasing, same structure - so what you see is what the swap node would have sent.

That's the whole point of the node. It's not a fancy LLM prompt-engineer; it's a transparency tool for a black box.

The inputs

Only four, and they're all easy:

• scope - face, head, or head+styling. This swaps in the region description: face keeps hair and ears, head replaces them, head+styling adds jewelry and makeup. Match it to whatever you'll set on the swap node.
• pathway - whole or crop. The crop path appends a clarifier telling Gemini it's looking at a tight close-up so it doesn't add shoulders or background.
• custom_hint - your own additions, spliced into the prompt. This is the lever for case-specific stuff: anti-beautify, expression direction, describing a private subject. You can test injection-escape behavior here.
• n_refs - how many reference images you plan to pass to the swap node. It drives the ref-count-conditional instruction: one ref gets a simple "match this identity," multiple refs get the multi-angle triangulation phrasing. Setting this wrong won't break anything, but the preview will lie about the usage instruction.

The output

A single prompt STRING. Read it in a text viewer, or pipe it into anything that takes text. That's it.

Install

Nothing special here - it ships in the same pack as the swap nodes:

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

Restart ComfyUI and it shows up in the NanoBanana FaceSwap category (also installable via ComfyUI Manager under "NanoBanana FaceSwap"). No API key needed for this node - it never calls out.

Gotchas

The honest limitation: this shows you the text, not the full request. The actual swap call also ships image parts (the target and refs) plus a JSON prompt structure, and the dry_run toggle on the swap nodes is the closer approximation of the real thing - it skips the API call but returns the structured prompt-plus-parts preview. Start with the Prompt Builder for the text, use dry_run when you need the whole picture. And if you're just trying to make sure a custom_hint didn't break the JSON, the dry_run status output on a swap node is the better tool - it burns no quota either.