Painter Qwen Image 2.1

Instruction-driven editing is how character consistency actually gets done now - the IP-Adapter/LoRA approach lost that fight somewhere around Kontext and Qwen-Edit, because telling a model "keep her face, change the jacket" beats bolting an identity adapter onto a sampler. Qwen-Image's edit line is the open-weight default for that job, and 2.1 is the newer revision of it.

This node is the whole front half of a Qwen Image 2.1 edit workflow in one box: reference images in, conditioning and a matching latent out. Nothing clever to configure, but the why is worth two minutes.

What it consolidates

On a stock 2.1 graph you'd wire a text encoder, then build a negative some other way, then an empty latent that matches your output size. Painter Qwen Image 2.1 does all three, and it does them in a way that keeps the two conditioning branches structurally identical.

The mechanism, since it explains the quirks: your reference images are resized once and then used twice. The RGB (composited on white if there's an alpha channel) goes into the text encoder's vision tower - which is the entire reason Qwen Image runs on a Qwen3-VL encoder rather than a text-only LLM: the -VL variant is what you pick when the pipeline needs the model to see something. The same image, with alpha intact, goes through the VAE, and those reference latents get attached to the conditioning so the DiT can splice them into its sequence. Raw latents, not a lossy description. That's the highest-fidelity route, and it's why the VAE has to be 2.1's.

The negative is the interesting part. There is no negative prompt field - negative is produced by zeroing the positive's text embeddings and pooled output, while keeping everything else (reference latents, image slots, attention mask) exactly as it was. So CFG is comparing two branches with identical structure and a different text vector, which is the only difference you want it to see.

Inputs and outputs

• clip - your Qwen3-VL-8B text encoder.
• vae - the 2.1 VAE: 64 channels, 16× spatial downsample. This is the trap. The 2509/2511/2512 qwen_image_vae is the older 16-channel one and does not go here.
• prompt - write sentences. The encoder is an LLM, so (word:1.4) weighting syntax is inert and tag soup gets you nothing.
• images - an autogrow stack, up to 16 slots, each taking one reference image (first frame only). The first slot is the edit baseline; the rest are scaled to the same scale as it.
• width / height - default 1024×1024, multiples of 32, up to 4096. Independent of your reference's aspect ratio: references are scaled to roughly the canvas area and never cropped, because cropping the content is how the model stops recognising the subject. So a portrait reference into a landscape canvas loses detail, not information.
• batch_size - number of latents.

Outputs: positive and negative into your sampler's two conditioning slots, and latent into its latent slot. The latent is a zeroed tensor sized width × height / 16 on the 64-channel grid - use it as-is rather than substituting your own EmptyLatent, or the reference grid and the canvas stop lining up.

More reference images means more tokens in the DiT sequence and a slower sampler. Sixteen is a capability, not a target.

Installing it

Same pack as the rest of these. ComfyUI Manager → search PainterNodes, or:

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

Dependencies are just soundfile and numpy; the model weights are the real cost. You need the 2.1 DiT, the 64-channel VAE and a Qwen3-VL-8B text encoder - a matched set. Older 2509/2511/2512 weights do not apply, and mixing them will fail in confusing ways (a 16-channel VAE against a 64-channel latent is not a subtle error).

If the node isn't there

The author says 2.1 support needs ComfyUI 0.36 or newer, and this node is written against the newer io.ComfyNode API. That matters more than usual for this pack: __init__.py imports each node module inside a try/except, so an import failure removes the node from the menu and prints one line to the console instead of breaking ComfyUI. If you've installed the pack, restarted, and Painter Qwen Image 2.1 simply isn't in the Add Node list, update ComfyUI first, then check the terminal for a [PainterNodes] Failed to import line before you go hunting for a missing dependency.

One behaviour worth knowing when the node "feels broken": internally it tolerates a missing VAE and falls back to keeping the vision tokens, feeding your references through the text encoder only - a weaker, text-only kind of conditioning that still produces an image. But the schema marks vae as required, so you can't reach that path by accident in the UI. If your edit is drifting, check which VAE is actually wired before you blame the prompt.