Qwen 2.1 UNION Image Reference Encode

There's a fork in this pack. Half of its workflows mean "make a new picture that follows this pose skeleton or edge map"; the other half mean "edit this photograph I already have." This node is the second half, and mistaking it for the first is why your subject keeps drifting into a stranger.

What it's for

The pack has two ways in. The plain one is ComfyUI's own TextEncodeQwenImage21, which the eight control workflows use: prepared map in, new image out. This node is for when the image already exists and you only want part of it changed - re-pose this photo, swap the jacket, keep the face. The union ControlNet steers layout; this node decides what's being edited and how big the canvas is. The shipped pose-edit workflow runs both together: a reference photo as the edit target, a pose map as the structure.

How it works

Qwen Image 2.1's text encoder is a vision-language model (qwen3vl_8b_int8_convrot.safetensors in the pack's download list), so a reference image gets consumed twice: downscaled into the VL encoder so the model can actually see what you're talking about, and VAE-encoded into the conditioning as reference latents so the pixels are there too. That's why the node wants both a clip and a vae - one is for meaning, one is for appearance.

Under the hood it's honest plumbing: it keys whatever you connect as image_1…image_3 - reference_image is image 1 - and hands them to the upstream TextEncodeQwenImage21, returning its three outputs untouched. Position is what matters. Image 1 defines the canvas; the rest are extra references.

The third output is the one people skip. latent is the sampling grid, sized to image 1's aspect ratio at roughly resolution² of area (default 1024) - a target area, not a maximum side. Don't wire an Empty Latent in here: an unrelated latent, especially at a different aspect ratio, shifts or loses the edit.

Inputs and outputs that matter

• reference_image - image 1. The photo you're editing, and the thing that sets the output canvas.
• reference_image_2 / reference_image_3 - optional extras. Name them in the prompt as <image1> and <image2>; that's how the encoder binds an image to a sentence.
• resolution - a target area, not a maximum side. 1024 in the shipped workflow; a 2:3 photo comes out at that pixel budget on its own ratio.
• prompt / negative_prompt - plain sentences. On LLM-encoded models (word:1.4) isn't ignored, it's fed in as literal punctuation. And the sample workflow samples at CFG 1.0, where ComfyUI skips the unconditional pass entirely, so the negative prompt does nothing there.

The outputs are positive and negative (into the sampler's matching slots) and latent (into latent_image). The shipped edit graph is UNETLoader → Apply Qwen Image 2.1 UNION (fed by the loader and a control map) → KSampler at 40 steps, euler/simple, CFG 1.0 → VAEDecode → SaveImage.

Install

You need ComfyUI 0.37.0 or newer. This node imports the upstream Qwen 2.1 encoder class directly, with no fallback - unlike the loader and apply nodes, which carry the pack's bundled compatibility copy for older builds. On an older ComfyUI, this is the node that breaks.

Grab the pack from ComfyUI Manager (search "Qwen Image 2.1 Fun ControlNet Union (T8)"), or:

cd ComfyUI/custom_nodes
git clone https://github.com/T8mars/Comfyui-Qwen-Image-2.1-Fun-Controlnet-Union-T8
# restart ComfyUI

Then the four model files, in exactly these folders: Qwen-Image-2.1-Fun-Controlnet-Union-ComfyUI.safetensors → models/controlnet/, qwen_image_2.1_int8_convrot.safetensors → models/diffusion_models/, qwen3vl_8b_int8_convrot.safetensors → models/text_encoders/, qwen_image_2.1_vae_bf16.safetensors → models/vae/. The int8-convrot quantisation is the reason a 30-series card can run this at all - it has no fp8 path.

Where people get burned

• Renaming the union checkpoint hides it. The loader only lists files starting with Qwen-Image-2.1-Fun-Controlnet-Union. Rename it and it vanishes from the dropdown with no error.
• No batches. Every image input, here and on the Apply node, must contain exactly one image; a batch trips an explicit error rather than silently using the first.
• The mode dropdown is a label. The union checkpoint carries no mode embedding, so it just reads the pixels. Nothing here preprocesses your photograph - "Canny" plus a raw portrait gives you a portrait-shaped mess.
• Masked editing is a nudge, not a guarantee. Connect the source to inpaint_image and a mask to mask on the Apply node, white regenerates and black preserves - but the model still re-emits the whole frame, so unmasked pixels move a little and the drift compounds edit over edit.
• It won't clone a person. A pose map plus a reference photo gives you structure and look, not a stranger's exact face or outfit - the README says so.

Weights are the Qwen Research License, non-commercial unless licensed separately; the pack code is GPL-3.0.