Flux FaceIR Paste Restored Face

The whole-image FaceIR pipeline is detect → restore → paste, and this is the last node in the chain. Flux FaceIR Paste Restored Face takes the square, freshly-restored face crop from Flux FaceIR Restore Face, warps it back onto the original degraded photo at the exact position and angle the face was found at, and blends the edge so you can't tell where the fix starts.

Skip this node and you've got a nice restored face with nowhere to live. It's the compositor, and compositing well is half of whether the result looks like a restoration or a bad photoshop.

How it works

Remember the align_params that Flux FaceIR Detect And Align Face exported? That bundle contains the inverse of the affine transform it used to straighten the face. This node applies that inverse transform to the restored crop, so the square face unwraps back onto the original photo in perfect register - same position, same tilt, same scale. It then builds a mask of the face region, erodes it, blurs it, and alpha-blends the restored face over the original pixels. The mask_softness parameter scales how much that feathered edge spreads: more softness, gentler blend, and a slightly larger zone where restored and original pixels mix.

The inputs

Only four, and they're all required:

• image - the original degraded full image. Critical detail: it must be the same image (same dimensions) that produced your align_params. The node validates this and errors otherwise.
• restored_face - the restored_face output from Flux FaceIR Restore Face.
• align_params - the align_params output from Flux FaceIR Detect And Align Face.
• mask_softness - default 1.0, range 0.25–4. The seam-feathering control. Lower it if the blend zone looks mushy; raise it if you can see the boundary.

Outputs are restored_image (the composited full photo, ready for a SaveImage node) and paste_mask (the actual alpha mask used - handy for inspecting where the blend happened, or feeding into other nodes).

Installing and using it

Same pack install as the rest: ComfyUI Manager (search Flux FaceIR) or git clone https://github.com/cosmicrealm/ComfyUI-Flux-FaceIR into custom_nodes + python install.py, then restart. The bundled full_image_restore.json workflow shows the whole graph wired end to end, including this node.

Where people get burned

• "IMAGE batch size … does not match restored face batch size" - you fed it an image batch and a restored_face batch of different lengths. The two must line up one-to-one.
• The dimension-mismatch error - you changed the source image after running Detect And Align (different width/height), then fed the old align_params. Re-run detection on the new image; the params are bound to a specific picture.
• The face comes back but the surroundings stay broken - expected. The README is explicit: only the face is pasted back. Reference images were guidance for the restorer, never content to paste. If the rest of the photo needs fixing too, that's an upscaler's job, not this node's.
• Hard seam on a high-contrast background - bump mask_softness a step or two rather than redoing the whole restoration.

It's the quiet node in a flashy pack, and it's the one that decides whether people say "how did you fix this photo" or "what happened to the pixels." Paste-back done well is invisible; this one gives you the knobs to make it that way.