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:
| Pathway | What happens | When it may help |
|---|---|---|
| Whole Image Swap | Sends the target image and identity references together. | A straightforward first choice when you want the model to see the full scene. |
| Crop & Composite Swap | Finds 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 Inpaint | Marks 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 Swap | Uses the mask-inpaint approach with a JSON-structured request. | When you want to try this alternative request format. |
| Painted Edit | Uses 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:
| Scope | Intended change | Intended preservation |
|---|---|---|
face | Facial features, jawline, and skin tone | Hair, hairline, and ears |
head | Face, hair, hairline, and ears | Neck and shoulders |
head+styling | Head plus details such as earrings, jewelry, makeup, and head or neck styling | More 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:
| Scope | Above face | Below face | Left | Right |
|---|---|---|---|---|
face | 25% | 25% | 25% | 25% |
head | 60% | 40% | 40% | 40% |
head+styling | 100% | 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, usehistogram_matchto help the returned crop fit the original image’s tones, and adjustfeather_pxto 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_levelsetting. - Nano Banana - Painted Edit: Edits a region you choose with a painted mask. Use
edit_promptto 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, and3x2. - 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:
- MediaPipe Face Detection: A fast, CPU-only option when MediaPipe is available.
- OpenCV YuNet: A detector intended to work well with side profiles. Its model file is downloaded automatically on first use.
- 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 anidentity_1batch; 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:
| Control | What it does |
|---|---|
dry_run | Shows 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_ms | Sets 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_px | Downscales identity references whose longest edge exceeds this value before sending them. The default is 1024; 0 disables the cap. |
auto_relax_on_refused | After 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:
| Model | Name in the extension | Supported image_size values | Notes |
|---|---|---|---|
gemini-3.1-flash-image | Nano Banana 2 | 512, 1K, 2K, 4K | Default model; offers the widest listed size range. |
gemini-3-pro-image | Nano Banana Pro | 1K, 2K, 4K | If you select 512, the request is sent as 1K. |
gemini-3.1-flash-lite-image | Nano Banana 2 Lite | 1K | Low-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_runshows what would be sent, so you can check prompts without using quota. - Control slow calls:
timeout_mslets you set how long each call may take. - Limit reference-image size:
ref_cap_pxreduces oversized references before upload, which can save bandwidth. - Optionally retry a refusal with model-default safety settings:
auto_relax_on_refusedprovides 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.
- Check the status for the refusal category.
- If surrounding scene content may be contributing, try Crop & Composite Swap to send only the head-area crop.
- If you need tighter control over the edited area, consider Painted Edit with a manually painted mask.
- You can try
auto_relax_on_refusedfor 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.
- Check that the target visibly contains the face you intend to edit.
- Try another available detector or select
autoto let the detector cascade try its options. - 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.
- Change
detectortoautoto allow the available methods to be tried in order. - 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.
- Read the status to identify the reported error.
- For a slow or timed-out request, consider increasing
timeout_ms. - For a temporary service or rate-limit issue, try the workflow again later.
- Use
dry_runif you want to inspect the prepared request without making another API call.
The edited crop looks mismatched with the surrounding image
- Inspect the debug sheet to see the detected and expanded boxes and the crop returned by the model.
- Try
histogram_matchto help the crop’s tones fit the original. - Adjust
feather_pxto soften a visible boundary. - 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
- ComfyUI-NanoBanana-FaceSwap repository: The project’s source documentation and current files.
- CHANGELOG.md: The full documented v0.2.0 changes.
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.
