FF API: Swap Face (Image)

Don't let the category throw you - this node lives under "FaceFusion API," and it has an api_token field sitting right there in the required inputs, which makes it look like you need to sign up for something. You don't. Leave api_token at its default of -1 and everything runs as local ONNX inference on your own GPU: no key, no network call, no account. That naming is a holdover from the real FaceFusion project, which does have a hosted paid tier - this ComfyUI wrapper by huygiatrng borrowed the category label without borrowing the actual API dependency.

SwapFaceImage is the pack's entry-level swap node - the README calls it, plainly, "Basic image face swap," and pairs it against its bigger sibling AdvancedSwapFaceImage. If you just want to drop a face onto a photo without fussing over mask blending, face selection rules, or occlusion handling, this is the one. It's also a reasonable pick for a comfy.icu API workflow where you'd rather expose two dropdowns to callers than fifteen.

How it works

It's the standard face-swap recipe the whole identity-preservation corner of the ecosystem shares: detect the face in your source photo, turn it into an identity embedding, detect the face in the target with your chosen detector, then run a swapper model that transplants the source identity onto the target's geometry and blends the seam. The swapper models on offer here - hyperswap, ghost, inswapper, blendswap, simswap, and a few others - are the same lineage InsightFace's original inswapper kicked off, the same one ReActor and Roop run on under different front ends. hyperswap_1c_256 is the default and the pack's own pick for the best quality-to-speed ratio.

Inputs and outputs that matter

• source_images / target_image (IMAGE) - the face you want, and the photo you're putting it into.
• face_swapper_model (default hyperswap_1c_256, 13 choices) - the default is a good starting point; switch to inswapper_128_fp16 if you're chasing raw speed on an RTX card.
• face_detector_model (default scrfd) - leave it, unless faces aren't being found.

What this node quietly gives up versus its Advanced sibling: no face-selector or sort-order field at all. If your target photo has more than one face, you don't get a say in which one gets swapped. The moment that matters to you, jump to AdvancedSwapFaceImage - same swap engine, with selection and masking exposed. Output is a single IMAGE, ready for Preview or Save.

Worth knowing if you ever turn this into a shipped product rather than a personal project: the swap models here, inswapper chief among them, descend from InsightFace's identity pipeline, and InsightFace licenses those specific weights for non-commercial research use. Fine for the overwhelming majority of what people build with this node - just something to check before you sell it.

Installing it

Via ComfyUI Manager: search Facefusion_comfyui, install, restart. Manually:

cd ComfyUI/custom_nodes
git clone https://github.com/huygiatrng/Facefusion_comfyui.git
cd Facefusion_comfyui
pip install -r requirements.txt

A full restart matters here, not just a browser refresh (more on why below). Nodes appear under the FaceFusion and FaceFusion API categories. First run auto-downloads the swapper model you picked (100–500MB depending which) plus the detector, straight into custom_nodes/Facefusion_comfyui/models/ - no manual model wrangling.

Common issues

Nodes don't show up after install. This bit a few people on the pack's own launch thread. Usual cause: pip install -r requirements.txt didn't actually complete inside ComfyUI's own Python - on a portable Windows install that means running pip from python_embeded, not your system Python. Re-run it in the right environment, then fully restart ComfyUI.

ONNX runtime fails to load a model. A partial or locked download is the usual culprit - this shows up as a Windows "system error" reading the .onnx file. Delete the offending file from custom_nodes/Facefusion_comfyui/models/ and let it re-download.

No faces detected. This node inherits the detector's default threshold rather than exposing it. If detection keeps failing on a dim or angled photo, that's your cue to move up to AdvancedSwapFaceImage or FaceDetectorNode, both of which let you lower score_threshold directly.

It's slow. ONNX falls back to CPU with no CUDA available, and the gap is real - GPU runs this 10–50x faster by the pack's own reckoning.