Y7 Flux.2 Klein Edit Multi-Ref

You've got a Klein checkpoint, a photo you want to change, and a couple more images holding the answer - a character sheet, the shirt, the room you're copying. ComfyUI's official multi-reference templates make you hand-patch reference_latents lists and babysit resize nodes. Y7 Flux.2 Klein Edit Multi-Ref collapses that into one node: pick the image being edited on the node, paint a mask if you want the change confined, wire the extras in, and it hands your sampler conditioning that's ready to run. It works with every FLUX.2 Klein variant, base or distilled, 4B or 9B.

How Klein actually uses references

Klein's text encoder is a Qwen3-VL model running with its visual tower switched off - it never sees your images. The references only reach the transformer as VAE latents appended to its token sequence, which explains two things:

• There is no reference syntax. <image1>, [Image 1], @ref2 - none of it is a real token. Refer to images in plain English by position: the on-node image is 1, ref_image_2 is 2, and so on. Always pair the number with a noun - "the man in Figure 1", not "the man in 1" - because a bare index has nothing to latch onto.
• Every reference costs tokens and VRAM. That's the whole reason ref_megapixels exists, and why the debug output reports a per-image token cost.

The inputs that matter

• vae (required) and image: wire in your Klein VAE and pick the picture from the input folder. Click into it to open the mask editor - paint there to confine the edit. The loaded image is reference 1.
• target_megapixels vs ref_megapixels: two separate budgets, both defaulting to 1.0. The first sets your output size - Klein is trained around 1 MP and degrades badly above it, so leave it. The second sizes each reference and never touches output resolution. It's your main VRAM lever - drop it to 0.5 when things get slow or OOM; a face or a style still comes through at half size.
• ref_image_2 … ref_image_8 (growable sockets): connect the empty slot and another appears, up to eight references total. They're IMAGE-only, unmaskable, and any alpha they carry is dropped. A socket holding a batch counts as several references.
• external_mask: an alternative to painting - a mask from Load Image (as Mask) or a segmentation node. It's stretched to fit the loaded image, so match the aspect ratio or the edge drifts. Watch the channel: Load Image (as Mask) starts on alpha, which returns an empty mask for a plain black-and-white file - switch it to red.

The masking gotcha that isn't a bug

Klein has no mask input of its own, and this is where people get burned. It's not an inpaint model - its in/out channels match, so ComfyUI drops the concat mask this node sets. The mask survives as the latent's noise_mask; the sampler restores everything outside it after each step, at 1/16 resolution. The settings follow from that:

• expand_mask defaults to 16 - one full latent cell - because a tightly painted edge otherwise loses a sliver to the downsample. Try 24–32 for hair and soft edges.
• feather_mask stays at 0 for a reason: a feather under ~16px is erased by the latent downsample, and a wider one smears a seam instead of blending. Do soft joins in pixel space after decode instead.
• binary_mask (on) hard-thresholds the finished mask so half-strength brush strokes don't turn into muddy blends.
• Set the sampler's denoise to 1.0. The unmasked area is restored every step regardless, so lowering denoise to "protect" it just weakens the edit.

Outputs and wiring

reference_latent is the edited image's latent - feed it to the sampler's latent input. positive and negative come back with the references and mask baked in. preview_image / preview_mask show the resize and mask before you commit, and debug is a text report of every image's size, token cost and mask state - wire it into any text viewer when a result surprises you.

Install

ComfyUI Manager → Custom Nodes Manager → search Y7 or Y7Nodes, or:

cd ComfyUI/custom_nodes
git clone https://github.com/yushan777/ComfyUI-Y7Nodes

Then restart ComfyUI. Two caveats: this node runs on ComfyUI's newer V3 node API (Autogrow sockets, the mask editor), so update ComfyUI if it doesn't show up; and the pack's README predates this node entirely, so treat the tooltips as the manual. Nothing downloads here - you supply the Klein checkpoint, its Qwen3 text encoder, and a VAE as usual. And since Klein is guidance-distilled, keep CFG at 1 (1.2–1.5 if anatomy wanders) with 4–8 Euler steps.

Recurring causes of confusion: the alpha-channel empty mask, expecting a mask where you painted none, and feathering in latent space. Wire debug into a text viewer and the node tells you exactly what happened.