Native ComfyUI nodes for Alibaba PAI's Qwen Image 2.1 Fun ControlNet Union. One Union checkpoint supports Canny, Depth, Grayscale, HED, Lineart, MLSD, Pose, Scribble, and masked inpainting. The nodes use ComfyUI's native Qwen Image 2.1 model and conditioning pipeline.

Canny control result

Requirements

ComfyUI 0.37.0 or newer with native Qwen Image 2.1 base-model support. This extension includes Union compatibility for releases before upstream PR #16519.
The Comfy-Org Qwen Image 2.1 base models.
The converted Union checkpoint.

Place the files in these ComfyUI directories:

| File | Directory | | --- | --- | | 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/ |

Install and use

Install Qwen Image 2.1 Fun ControlNet Union (T8) from ComfyUI Manager, or clone this repository into ComfyUI/custom_nodes/. Restart ComfyUI.

Copy the sample files from assets/ to ComfyUI/input/, then drag a UI workflow from workflows/ onto the canvas. The folder includes eight control workflows, pose inpainting, reference-image editing, and reference-image editing with masked inpainting. Files ending in .api.json are API prompts, not canvas workflows.

Connect a prepared Canny, Depth, Grayscale, HED, Lineart, MLSD, Pose, or Scribble map to Apply Qwen Image 2.1 UNION. The mode selector describes the map; it does not preprocess a photograph. To edit a photograph, connect it to Qwen 2.1 UNION Image Reference Encode and connect that node's positive, negative, and latent outputs to the sampler. The reference image sets the edit's canvas size. For masked edits, also connect the source image to inpaint_image and a mask to mask; white guides regeneration and black guides preservation. The mask conditions the model and does not guarantee unchanged pixels outside the mask.

For two images, reference_image is image 1, the edit target that determines output aspect ratio; reference_image_2 is an additional visual reference. Mention them as <image1> and <image2> in the prompt. Always connect this encoder's latent to the sampler. An unrelated empty latent, especially one with a different aspect ratio, can shift or lose the edit. Prepare the control map at the target canvas aspect ratio to avoid stretching it. Structural control does not guarantee an exact face or outfit transfer from another person.

| Input | Image to provide | | --- | --- | | control_image | Preprocessed edge, depth, pose, or other selected control map | | reference_image | Image 1: original photograph to edit; determines output canvas | | reference_image_2 / _3 | Additional appearance or style references | | inpaint_image + mask | Source photograph and white-to-edit mask for guided local inpainting |

Each connected condition input (control image, inpaint image, or mask) must contain one image; the native patch otherwise uses only the first item of each batch. To sample multiple seeds from the same control, repeat the latent after the aspect-ratio node. Extremely wide or tall inputs that would produce an output side above 4096 pixels are rejected; reduce resolution or crop/pad the input.

The loader validates the 16-block Union checkpoint. The pictured Canny result used the default 40 steps at 800×1312 output.

License and provenance

Original adapter code: MIT. Bundled ComfyUI Union compatibility: GPL-3.0, adapted from upstream PR #16519; the distributed package is GPL-3.0. Model weights: Qwen Research License, non-commercial use only unless separately licensed by Qwen. The converted checkpoint preserves tensor payload bytes; only safetensors header metadata changes. Checksums are in MODEL_SHA256.json, and the conversion script is convert_union.py.

T8 links

Bilibili · YouTube · API · Free gallery · Online AI apps · ComfyUI bundle · Hugging Face