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, anddebug_sheetbefore adding more references or processing a batch. - Enable
dry_runwhile refiningcustom_hintor checking request construction. Turn it off when you need a generated swap; a dry run skips the API call. - Keep
scopeat its defaultfacewhen 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_pxat1024as a practical starting point for large references. Set it to0only when you specifically need to send references without that size cap. - Use a fixed
seedwhile comparinggrid_mode, references, or hints. This keeps one request setting constant, although identical results are not guaranteed. - For a slow call, adjust
timeout_msaccording 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_2throughidentity_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_keyand your configured credential method. Usedry_runto inspect request construction without making a live API call.
API call timed out
- Explanation: A call may exceed
timeout_ms. The default allows180000milliseconds per call; the exact timeout message depends on the backend and is not shown here. - Solution: Increase
timeout_msif the service is responding slowly, up to the allowed maximum of600000. 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_thresholdis set toBLOCK_NONE. The supplied source does not provide a literal refusal message. - Solution: Review the target, references, and
custom_hint. You can tryauto_relax_on_refusedfor one retry using model-default safety settings, but acceptance is not guaranteed.
No image connected to a required input
- Explanation:
target_imageandidentity_1are requiredIMAGEconnections. Without either, the node cannot prepare the target and its first reference. - Solution: Connect a target scene to
target_imageand an identity reference toidentity_1, then run the node again.
Unexpected identity reference used
- Explanation: For each connected
identity_2throughidentity_6, the node takes only the first image from that input's batch. The batching ofidentity_1follows 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_axisdetermines 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_axisand the batches connected totarget_imageandidentity_1. Run one image at a time to identify the pairing you need.
Network or proxy connection failed
- Explanation: A connected
networkroute 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_runenabled, 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 setdry_runtoFalsewhen you are ready to make the API call.
Reference image is larger than expected
- Explanation:
ref_cap_pxcontrols a longest-edge cap for identity references; setting it to0disables the cap. It does not specify the final output size. - Solution: Set
ref_cap_pxto a nonzero value within its allowed range to limit reference dimensions, and setimage_sizeseparately for the requested generated-image size.
