Nano Banana - Face Swap (Whole Image)

NanoBananaWholeImageSwap is the flagship of this pack and the right place to start: it sends the full target image plus up to six identity references to Google's Nano Banana, asks it to redraw the face, and hands you the result. No local model, no face-detector cascade, no crop math - just the API call and whatever the model decides. That simplicity is the appeal, and also the ceiling.

"Whole image" is the honest description. Gemini sees the entire frame and rewrites the whole thing to satisfy the edit, then the pack composites its mask back so the pixels that should have stayed identical mostly do. The README calls this pathway the "Face Detailer mode" for same-character refinement - you've already got a face you roughly like, and you want it cleaned up or nudged toward a reference - and that's exactly the sweet spot.

How it works

The request construction is where the pack earns its keep. The prompt templates deliberately avoid vocabulary that raises Gemini's safety-classifier sensitivity - no "swap", no "replace face", no "deepfake". Instead it says "edit," "redraw," "match identity." That's not hand-waving; those words measurably change refusal rates on this model, and the whole pack is engineered around that fact.

On success you get the edited image plus a per-pixel diff mask of the changed region - the pack computes what actually moved, so you can inspect or reuse the edit boundary. On refusal you get a red-tinted placeholder and a status string explaining which category fired.

Inputs that matter

• api_key / model - Gemini key (or GEMINI_API_KEY in the environment) and the model. gemini-3.1-flash-image-preview (Nano Banana 2) is the default; gemini-3-pro-image-preview is the slower, higher-quality Pro; gemini-2.5-flash-image is the older Nano Banana 1.
• target_image + identity_1..identity_6 - the frame to edit and the reference faces. This is the whole identity story: one ref works, more refs triangulate. grid_mode flips between sending them separate (separate_refs) and composing an auto sheet (auto_sheet) - reach for the sheet when you have 4+ angles.
• scope - the pack's semantics: face replaces eyes/nose/mouth/jawline/skin tone but preserves hair, hairline, and ears; head replaces the whole head; head+styling throws in jewelry and makeup.
• safety_threshold (BLOCK_NONE default) - how strict Gemini's filter should be. Note the pack's caveat: some BLOCK_NONE refusals actually relax if you drop auto_relax_on_refused on and let the model use its own defaults.
• image_size (2K default) - 1K/2K/4K output. 4K is slower and pricier.
• seed, batch_axis - seed for determinism; batch_axis iterates frames (target) or identities (identity) as separate API calls.
• The v0.2 quality-of-life set: dry_run (free prompt preview), timeout_ms, ref_cap_px (downscale refs to 1024 - saves bandwidth and actually improves identity transfer, because 4K skin-pore detail confuses the model), auto_relax_on_refused, and network for a proxy route node.

Outputs

The standard four: image (result, or red-tinted on refusal), status (OK/REFUSED:<category>/ERROR:<reason>), mask (per-pixel diff mask of the changed region), and debug_sheet - the identity sheet you used, or a side-by-side input/output comparison.

Install

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

Restart ComfyUI, or install via ComfyUI Manager under "NanoBanana FaceSwap." You need a Gemini API key. The good news about being API-based: no multi-gigabyte checkpoint, no VRAM ceiling - the bad news: every queue is a paid API call (~$0.039 for a single Flash image, more for Pro/4K), and IS_CHANGED returns NaN so nodes always re-run.

Troubleshooting

• REFUSED:<category> - the classifier fired. First try auto_relax_on_refused; then step down the pack's ladder: Crop & Composite for scene-content refusals, Mask Inpaint or the Unbiased path for identity refusals.
• Hair/ears changed when you wanted only the face - you're on scope=head. Drop to face.
• Result too smoothed / plastic - Flash's look at high strength. Bump the model to Pro, or accept that and fix details downstream.
• Everything changes, nothing matches - classic ref problem. Add more angles, use a composed sheet, and set ref_cap_px - surprisingly, less detail per ref often locks identity better.
• Face near the image edge comes back misaligned - that's the whole-image path showing its limits; the Crop & Composite node was built for exactly this case.