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 > Nano Banana - Face Swap (Whole Image)

ComfyUI Node: Nano Banana - Face Swap (Whole Image)

Class Name

NanoBananaWholeImageSwap

Category
NanoBanana FaceSwap
Author
ixmxamar (Account age: 770days)
Extension
ComfyUI-NanoBanana-FaceSwap
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

Nano Banana - Face Swap (Whole Image) Description

Uses a remote image model to swap identities in a target scene, with multiple references and batching.

Nano Banana - Face Swap (Whole Image):

NanoBananaWholeImageSwap uses a remote image model to create a whole-image identity swap. You provide a scene and identity reference imagery, and the node asks the model to produce an edited image using those references. It supports several references, batch processing, and a preview mode that lets you inspect what would be sent before making an API call. The swap itself is performed by an imported backend whose implementation is not shown here, so the source does not establish precisely which features will change, how closely the scene will be preserved, or what area the returned mask represents.

Nano Banana - Face Swap (Whole Image) Input Parameters:

api_key

The credential used for the API call. Enter it in the password-style field; its default is an empty string. The node passes the value through an API-key resolver, but the supplied source does not show whether that resolver can obtain a key from elsewhere. If your setup requires a key here, an empty value may prevent a live swap.

model

Selects the image model passed to the swap backend. The default is the first entry in the IMAGE_MODELS dropdown. The available model names are not included in the supplied source, so choose from the options shown in your installation. Model choice is also used when the node appends a cost-estimate suffix to the status of a live run.

target_image

The image containing the scene you want to edit. This required IMAGE input can contain a batch; the node converts it into individual images before processing. Its contents give the backend the target scene for each swap, but the supplied source does not guarantee that every detail of that scene will remain unchanged.

identity_1

The required identity reference image. It supplies the first reference for the swap and can contain a batch. The batch_axis setting determines how the node's batch iterator uses multiple images from this input; the exact pairing rules are not visible in the supplied source. There is no default image.

scope

Selects the requested swap scope sent to the backend. Its default is face. The complete SCOPES dropdown and the backend's interpretation of each choice are not shown, so treat the displayed options as requests to the model rather than guarantees about which pixels will change.

grid_mode

Controls how references are presented to the swap backend. Its default is separate_refs; the complete GRID_MODES dropdown and the assembly behavior are not shown. Use the options displayed in your installation, and check the result when changing modes because reference presentation may affect the generated image.

custom_hint

Optional text passed to the backend as an additional instruction. It defaults to an empty, multiline field. Use it to state a concise visual intention, such as which identity should appear in the target scene, while recognizing that the supplied source does not show the final prompt or guarantee that the model will follow the hint exactly.

safety_threshold

Selects a safety setting passed to the backend. Its default is BLOCK_NONE; the remaining SAFETY_LEVELS options and their exact behavior are not included in the supplied source. This setting does not guarantee that a request will be accepted: the node also provides an optional retry setting for a model refusal.

seed

An integer passed to the backend to influence generation. Its default and minimum are 0, and its maximum is 2147483647. Keeping it the same can help you compare settings, but the supplied source does not establish that repeated API calls will produce identical images.

batch_axis

Selects how the node builds its processing batch from target images and identity references. Its default is target; the full BATCH_AXES dropdown and pairing rules are not included in the supplied source. Each iteration makes a separate backend call, and the results are collected into batched image, mask, and debug outputs.

image_size

Selects the requested image size passed to the backend. Its default is 2K; the complete IMAGE_SIZES dropdown is not shown. The setting also contributes to the cost-estimate suffix on live runs. It does not set the size of identity references sent to the backend; ref_cap_px controls that separately.

identity_2

An optional additional IMAGE identity reference, with no default image. If connected, the node includes it among the references; when this input contains a batch, only its first image is used. Use it when the swap benefits from another view or example, while checking the output to see how the backend uses multiple references.

identity_3

An optional additional IMAGE identity reference, with no default image. The node uses only the first image if you connect a batch here. It is passed along with the other connected references, but the supplied source does not define a priority among them.

identity_4

An optional additional IMAGE identity reference, with no default image. The node uses only the first image from this input and includes it in the references for processing. Connect it when you have another useful identity example rather than assuming more references will always improve the result.

identity_5

An optional additional IMAGE identity reference, with no default image. If supplied, its first image is used as a reference; any later images in its batch are not used by this node's preparation code. Review the generated image to judge whether this reference helps.

identity_6

An optional additional IMAGE identity reference, with no default image. This is the last reference socket shown in the interface, and the node uses only the first image supplied to it. The backend's exact treatment of all connected references is not visible in the supplied source.

dry_run

A BOOLEAN that defaults to False. When enabled, it tells the backend to skip the API call and return a structured preview of the prompt and parts that would have been sent, without consuming API quota, according to the input tooltip. Use it to inspect a custom_hint or troubleshoot request construction. The supplied source does not define the exact appearance of the preview outputs.

timeout_ms

The per-call API timeout in milliseconds. Its default is 180000 (three minutes), minimum is 5000, maximum is 600000, and the control changes in steps of 1000. Lower it when you prefer a quicker failure on a stuck call; raise it when a legitimate render needs more time. In a batch, this setting applies to each backend call.

ref_cap_px

The maximum longest-edge size, in pixels, for identity references before they are sent. Its default is 1024, minimum is 0, maximum is 4096, and the control changes in steps of 64; 0 disables this cap. Reducing large references can save bandwidth. The input tooltip also reports that 1024 empirically helps identity transfer, but this is guidance rather than a guaranteed result.

auto_relax_on_refused

A BOOLEAN that defaults to False. When enabled, it instructs the backend to retry once without explicit safety_settings if the model refuses, using model defaults for that retry. It is not a guarantee that a refused request will succeed, and it may result in an additional API call.

network

An optional NB_NETWORK connection, with no default connection specified. You can connect a NanoBanana

  • Network Route node to route this swap's API call through its configured proxy, such as a chosen egress location. The supplied source does not show how that route is configured or validated.

Nano Banana - Face Swap (Whole Image) Output Parameters:

image

The resulting IMAGE output. The node collects one image returned by the backend for each batch iteration and converts the collection into an image tensor. On a live run, inspect this output to judge the swap; on a dry run, do not assume it is a completed edit because the API call is skipped.

status

A STRING containing the backend status for each iteration. For multiple iterations, individual statuses are joined with semicolons. On a live run, the node appends a cost-estimate suffix based on the selected model, number of calls, and image size; it does not append that suffix during a dry run. The exact backend status wording and estimate format are not shown in the supplied source.

mask

A MASK output assembled from the masks returned by the backend for each iteration. It can be used in a downstream mask workflow, but the supplied source does not define whether it marks the changed area, a face region, or something else. Inspect it alongside image before relying on it for precise compositing.

debug_sheet

An IMAGE output assembled from the backend's debug-sheet images, one per iteration. Use it to inspect information the backend provides about a request or result. The supplied source does not define the sheet's layout or contents, so interpret it alongside status rather than assuming particular labels or panels will be present.

Nano Banana - Face Swap (Whole Image) Usage Tips:

  • Start with one target image and one clear identity reference. Inspect image, mask, status, and debug_sheet before adding more references or processing a batch.
  • Enable dry_run while refining custom_hint or checking request construction. Turn it off when you need a generated swap; a dry run skips the API call.
  • Keep scope at its default face when that matches your goal. For other goals, select only from the scope options available in your installation and verify the resulting image.
  • Leave ref_cap_px at 1024 as a practical starting point for large references. Set it to 0 only when you specifically need to send references without that size cap.
  • Use a fixed seed while comparing grid_mode, references, or hints. This keeps one request setting constant, although identical results are not guaranteed.
  • For a slow call, adjust timeout_ms according to whether you need faster failure or more rendering time. Remember that a batch can make multiple calls, and its live-run status includes a cost estimate.
  • If you connect a batch to identity_2 through identity_6, place the intended reference first: this node selects only the first image from each of those inputs.

Nano Banana - Face Swap (Whole Image) Common Errors and Solutions:

Missing or invalid API key

  • Explanation: A live request may fail if the backend cannot authenticate. This is a possible failure category, not a literal error message shown in the supplied node source.
  • Solution: Check api_key and your configured credential method. Use dry_run to inspect request construction without making a live API call.

API call timed out

  • Explanation: A call may exceed timeout_ms. The default allows 180000 milliseconds per call; the exact timeout message depends on the backend and is not shown here.
  • Solution: Increase timeout_ms if the service is responding slowly, up to the allowed maximum of 600000. If you prefer to detect stalled calls sooner, lower it instead.

Model refused the request

  • Explanation: The model can refuse a request even when safety_threshold is set to BLOCK_NONE. The supplied source does not provide a literal refusal message.
  • Solution: Review the target, references, and custom_hint. You can try auto_relax_on_refused for one retry using model-default safety settings, but acceptance is not guaranteed.

No image connected to a required input

  • Explanation: target_image and identity_1 are required IMAGE connections. Without either, the node cannot prepare the target and its first reference.
  • Solution: Connect a target scene to target_image and an identity reference to identity_1, then run the node again.

Unexpected identity reference used

  • Explanation: For each connected identity_2 through identity_6, the node takes only the first image from that input's batch. The batching of identity_1 follows a separate iterator whose pairing rules are not shown here.
  • Solution: Put the intended image first in each optional reference input, or connect a single image to each. Test a small batch before processing a larger one.

Unexpected number of results or status entries

  • Explanation: batch_axis determines the number of processing iterations, and the node joins multiple statuses with semicolons. The exact iterator rules are outside the supplied source.
  • Solution: Check the selected batch_axis and the batches connected to target_image and identity_1. Run one image at a time to identify the pairing you need.

Network or proxy connection failed

  • Explanation: A connected network route may affect whether the API call reaches the service. The supplied source does not provide specific proxy error strings.
  • Solution: Check the NanoBanana - Network Route node's configuration. Where appropriate for your setup, test without that optional connection to narrow down the cause.

Dry run produced no completed swap

  • Explanation: With dry_run enabled, the backend is instructed to skip the API call. A preview is expected rather than a live generated edit.
  • Solution: Inspect the preview and status, then set dry_run to False when you are ready to make the API call.

Reference image is larger than expected

  • Explanation: ref_cap_px controls a longest-edge cap for identity references; setting it to 0 disables the cap. It does not specify the final output size.
  • Solution: Set ref_cap_px to a nonzero value within its allowed range to limit reference dimensions, and set image_size separately for the requested generated-image size.

Nano Banana - Face Swap (Whole Image) Related Nodes

Go back to the extension to check out more related nodes.
ComfyUI-NanoBanana-FaceSwap
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.

Nano Banana - Face Swap (Whole Image)