Save 4 hours! We auto-setup your workflow! Free!

Drop your workflow.json — we handle every dependency, custom node, and model. Just open the link and run.

Auto-Setup Workflow Json (Free) Now!
ComfyUI > Nodes > ComfyUI-NanoBanana-FaceSwap

ComfyUI Extension: ComfyUI-NanoBanana-FaceSwap

Repo Name

ComfyUI-NanoBanana-FaceSwap

Author
ixmxamar (Account age: 770 days)
Nodes
View all nodes(1)
Latest Updated
2026-10-02
Github Stars
0.0K

How to Install ComfyUI-NanoBanana-FaceSwap

Install this extension via the ComfyUI Manager by searching for ComfyUI-NanoBanana-FaceSwap
  • 1. Click the Manager button in the main menu
  • 2. Select Custom Nodes Manager button
  • 3. Enter ComfyUI-NanoBanana-FaceSwap in the search bar
After installation, click the Restart button to restart ComfyUI. Then, manually refresh your browser to clear the cache and access the updated list of nodes.

Visit ComfyUI Online for ready-to-use ComfyUI environment

  • Free trial available
  • 16GB VRAM to 80GB VRAM GPU machines
  • 400+ preloaded models/nodes
  • Freedom to upload custom models/nodes
  • 200+ ready-to-run workflows
  • 100% private workspace with up to 200GB storage
  • Dedicated Support

Run ComfyUI Online

ComfyUI-NanoBanana-FaceSwap Description

ComfyUI-NanoBanana-FaceSwap uses Google’s Nano Banana image models to replace a face or head using identity references, with whole-image, cropped, inpainted, or manually masked editing options.

ComfyUI-NanoBanana-FaceSwap Introduction

ComfyUI-NanoBanana-FaceSwap is a set of ComfyUI nodes for editing a person’s face or head in an image using Google’s Nano Banana image models. You provide a target image—the picture you want to change—and one or more identity references showing the appearance you want the result to follow.

The extension offers several ways to make the edit. You can send the whole image to the model, work on a smaller crop around the head, mark a detected face for inpainting, or paint the exact area you want edited. This flexibility is useful when a full-image request changes too much of the scene or is refused because of surrounding content.

A smaller crop is not a guaranteed way around a refusal. It may help when background objects or clothing are the issue, but it can increase refusals when the model’s safety checks respond to the identity itself, such as a real person or someone perceived as a minor.

All nodes appear in ComfyUI under NanoBanana FaceSwap.

How ComfyUI-NanoBanana-FaceSwap Works

Think of the target image as the canvas and the identity references as visual guidance for the edit. The extension prepares the images and an editing instruction, sends them to a Gemini image model, then returns the result to your ComfyUI workflow.

The main pathways differ in how much of the target image the model sees and edits:

PathwayWhat happensWhen it may help
Whole Image SwapSends the target image and identity references together.A straightforward first choice when you want the model to see the full scene.
Crop & Composite SwapFinds the face, expands a crop around it, edits that crop, then blends it back into the original image.When surrounding scene content causes a refusal or you want to preserve more of the original image.
Mask InpaintMarks the detected face area and asks the model to fill that region, then composites the result back.When you want the edit guided by an automatically detected face region.
Unbiased Face SwapUses the mask-inpaint approach with a JSON-structured request.When you want to try this alternative request format.
Painted EditUses an area you paint yourself and an edit prompt.When automatic face selection does not match the area you want to change.

For Crop & Composite Swap, the extension keeps the detected face centered while preparing the crop—even when the face is close to an image edge. After the model edits that crop, the extension places it back at the same position and blends its edges. This helps avoid a head edit landing out of alignment with the body.

The swap prompts describe the task with editing language such as “redraw” and “match identity.” If you want to inspect the instruction before making a request, use Face Swap Prompt Builder.

ComfyUI-NanoBanana-FaceSwap Features

Swap scope

The scope setting controls what the identity edit is intended to cover:

ScopeIntended changeIntended preservation
faceFacial features, jawline, and skin toneHair, hairline, and ears
headFace, hair, hairline, and earsNeck and shoulders
head+stylingHead plus details such as earrings, jewelry, makeup, and head or neck stylingMore of the surrounding image

Choose face if you like the target’s existing hairstyle. Choose head when the reference hairstyle matters. Choose head+styling when accessories or styling are part of the look you want to carry over.

In Crop & Composite Swap, scope also changes how far the crop extends beyond the detected face. A wider scope gives the model more context for hair and accessories:

ScopeAbove faceBelow faceLeftRight
face25%25%25%25%
head60%40%40%40%
head+styling100%80%70%70%

These percentages are based on the detected face box, not the dimensions of the entire image.

Nodes and editing controls

  • Nano Banana - Face Swap (Whole Image): The default, direct pathway. It accepts a target and up to six identity references. Its mask output shows which pixels changed.
  • Nano Banana - Face Swap (Crop & Composite): Detects and edits a head-area crop. You can adjust crop_size, use histogram_match to help the returned crop fit the original image’s tones, and adjust feather_px to soften the blend at the crop boundary.
  • Nano Banana - Face Swap (Mask Inpaint): Marks a detected face polygon in red for the model and composites the filled area back into the target.
  • Nano Banana - Unbiased Face Swap: A mask-inpaint variation that uses a JSON-structured request and offers an optional thinking_level setting.
  • Nano Banana - Painted Edit: Edits a region you choose with a painted mask. Use edit_prompt to describe the change; identity references are optional.
  • Load Image (Paint Mask): Loads an image and lets you paint the mask within the node for use with Painted Edit.
  • Identity Ref Obfuscator: Perturbs identity-reference images before they are sent.
  • Identity Sheet Composer: Arranges up to six references into one labeled grid. Layout choices include auto, 2x2, and 3x2.
  • Face Swap Prompt Builder: Lets you preview the prompt used by the swap nodes. You can also add your own guidance through custom_hint.

Face detection for Crop & Composite Swap

With detector=auto, the crop pathway tries these methods in order:

  1. MediaPipe Face Detection: A fast, CPU-only option when MediaPipe is available.
  2. OpenCV YuNet: A detector intended to work well with side profiles. Its model file is downloaded automatically on first use.
  3. Gemini vision bounding box: A last-resort method that makes one additional API call.

You can select a detector explicitly instead of using auto. If that detector is unavailable, the node reports ERROR:detector_unavailable:<name> rather than silently choosing another one.

Results, batches, and request controls

The swap nodes provide four outputs: an edited image, a text status, a mask, and a debug sheet. The mask can help you inspect where an edit occurred. The debug sheet helps you inspect the inputs or the crop stages: Whole Image Swap shows the identity sheet when auto_sheet is used, or an input/output comparison; Crop & Composite Swap shows the detected face box, expanded box, crop sent to the model, and returned crop.

For repeated edits, batch_axis determines what changes between calls:

  • target (default): Edit each image in a target batch using the same identity references.
  • identity: Edit against each image in an identity_1 batch; references 2–6 remain fixed.

Batch items run one after another, each as a separate API request. A refusal for one item does not stop the remaining items. Batched statuses are joined with semicolons.

The following optional controls are available on every swap node:

ControlWhat it does
dry_runShows the prompt and request parts that would be sent without calling Gemini or using quota. Useful for checking a custom_hint or edit_prompt.
timeout_msSets the timeout for each API call. The default is 180000 ms; a shorter value fails faster on a stalled call, while a longer value may suit a slow render.
ref_cap_pxDownscales identity references whose longest edge exceeds this value before sending them. The default is 1024; 0 disables the cap.
auto_relax_on_refusedAfter a refusal, retries once without explicit safety_settings, leaving the SDK to use model defaults. This may help in some cases, but does not guarantee acceptance.

The status may include an indicative cost estimate. It is not a bill: actual cost depends on input and output usage that the extension does not measure.

ComfyUI-NanoBanana-FaceSwap Models

Select a model according to the image size you need and the available options below:

ModelName in the extensionSupported image_size valuesNotes
gemini-3.1-flash-imageNano Banana 2512, 1K, 2K, 4KDefault model; offers the widest listed size range.
gemini-3-pro-imageNano Banana Pro1K, 2K, 4KIf you select 512, the request is sent as 1K.
gemini-3.1-flash-lite-imageNano Banana 2 Lite1KLow-latency, low-cost option. Other selected sizes are sent as 1K.

For example, if you need a 2K or 4K request, choose Nano Banana 2 or Nano Banana Pro. If 1K suits your workflow and you want the low-latency, low-cost option described by the author, try Nano Banana 2 Lite.

What's New with ComfyUI-NanoBanana-FaceSwap

v0.2.0

The documented v0.2 changes add more ways to inspect and control requests:

  • Preview without an API call: dry_run shows what would be sent, so you can check prompts without using quota.
  • Control slow calls: timeout_ms lets you set how long each call may take.
  • Limit reference-image size: ref_cap_px reduces oversized references before upload, which can save bandwidth.
  • Optionally retry a refusal with model-default safety settings: auto_relax_on_refused provides one additional attempt, without guaranteeing a different outcome.
  • See an indicative cost in status: The estimate gives you a rough guide for a call or batch, not a measured final charge.
  • More precise transient-error retries: Retry detection is less likely to mistake an unrelated number in an error message for an HTTP status code.
  • Safer handling of user-supplied prompts, painted-mask data, and concurrent detector-model downloads: These changes improve the reliability of workflows that use those inputs.

See the repository’s CHANGELOG.md for the full v0.2.0 change set.

Troubleshooting ComfyUI-NanoBanana-FaceSwap

Start by connecting the node’s status output so you can see what happened. OK means the request succeeded; REFUSED:<category> identifies a safety refusal; and ERROR:<reason> identifies another failure. The extension uses tinted placeholder images for some failures, so a returned image does not always mean an edit succeeded.

The result is red-tinted or status says REFUSED:<category>

The model refused the request. Whole Image Swap returns a red-tinted target; Crop & Composite Swap tints only the affected face-box region.

  1. Check the status for the refusal category.
  2. If surrounding scene content may be contributing, try Crop & Composite Swap to send only the head-area crop.
  3. If you need tighter control over the edited area, consider Painted Edit with a manually painted mask.
  4. You can try auto_relax_on_refused for one retry with model-default safety settings.

Cropping and retrying are not universal solutions. In particular, a tighter face crop can make an identity-related refusal more likely.

Crop & Composite Swap says ERROR:no_face_detected

The crop pathway could not locate a face.

  1. Check that the target visibly contains the face you intend to edit.
  2. Try another available detector or select auto to let the detector cascade try its options.
  3. If automatic face selection still does not suit the image, use Painted Edit to mark the desired area yourself.

This failure returns a yellow-tinted placeholder.

Status says ERROR:detector_unavailable:<name>

A detector you selected explicitly is not available.

  1. Change detector to auto to allow the available methods to be tried in order.
  2. If you specifically need MediaPipe, make sure MediaPipe is available in the ComfyUI environment.

The result is yellow-tinted or status says ERROR:<ExceptionClass>

An API call failed after applicable retries, or another error occurred. Temporary errors such as rate limits, certain server errors, and timeouts are retried up to three times with increasing delays.

  1. Read the status to identify the reported error.
  2. For a slow or timed-out request, consider increasing timeout_ms.
  3. For a temporary service or rate-limit issue, try the workflow again later.
  4. Use dry_run if you want to inspect the prepared request without making another API call.

The edited crop looks mismatched with the surrounding image

  1. Inspect the debug sheet to see the detected and expanded boxes and the crop returned by the model.
  2. Try histogram_match to help the crop’s tones fit the original.
  3. Adjust feather_px to soften a visible boundary.
  4. Review the scope: a broader scope sends more hair and styling context to the model.

Frequently asked questions

Can I check a prompt without spending API quota?
Yes. Enable dry_run to preview the prompt and request parts without calling Gemini.

Can I edit several targets or try several identities in one workflow?
Yes. Use batch_axis=target for multiple target images with fixed references, or batch_axis=identity to cycle through a batch in identity_1. Calls run sequentially.

Will one refused image stop my batch?
No. Each item gets its own call and retry handling, so subsequent items continue.

Why does the selected output size change with some models?
Nano Banana Pro sends a 512 selection as 1K. Nano Banana 2 Lite sends any size other than 1K as 1K.

Does the cost shown in status equal my actual charge?
No. It is an indicative estimate; actual cost depends on usage that the extension does not measure.

Learn More about ComfyUI-NanoBanana-FaceSwap

Within ComfyUI, Face Swap Prompt Builder is also a useful learning tool: it shows the instruction behind a swap before you run it, making it easier to understand how your scope and custom guidance contribute to the request.

ComfyUI-NanoBanana-FaceSwap Related Nodes

RunComfy
Copyright 2025 RunComfy. All Rights Reserved.

RunComfy is the premier ComfyUI platform, offering ComfyUI online environment and services, along with ComfyUI workflows featuring stunning visuals. RunComfy also provides AI Models, enabling artists to harness the latest AI tools to create incredible art.

ComfyUI-NanoBanana-FaceSwap detailed guide | ComfyUI