Eric Qwen-Image UltraGen (ControlNet)
Canny, depth, pose, or soft-edge control
- pipeline
- controlnet
- control_image
- upscale_vae
- image
Eric Qwen-Image UltraGen CN is the ControlNet-guided version of the pack's flagship: the same multi-stage progressive generation as UltraGen, but Stage 1 (and optionally Stage 2) is steered by a control image - Canny edges, soft edges, a depth map, or an OpenPose skeleton - using the InstantX Qwen-Image ControlNet-Union model. If you want a generated image that follows your composition instead of whatever the prompt happens to produce, this is the node.
It's also the honest answer to a question the KB's controlnet doc keeps coming back to: on a 2026 DiT base like Qwen-Image, ControlNet still wins when you need real spatial control - drawn or extracted maps, per-condition strength, scheduled guidance. Qwen-Edit took the pose-and-reference slice of the old ControlNet job, but for "render this Canny sketch as a full scene" you still want an actual ControlNet. That's this node.
The inputs that make it different
controlnet- theQWEN_IMAGE_CONTROLNETfrom Eric Qwen-Image ControlNet Loader (loads the Union model once; you pick the mode here, not at the loader).control_image- the map: canny, depth, pose, or soft edge.cn_fit_mode- how the control image is fitted to generation dimensions:match_control(override aspect ratio to match the control image) or the crop/pad variants (withpad_edge_blurcontrolling feathering into the padded zone).match_controlis the safest default when your map's aspect ratio matters.cn_type-canny,soft_edge,depth,pose. Pick what your control image is.
The auto-scale magic
cn_auto_scale (default True) is the interesting engineering here. ControlNet strength is normally a manual fight - different fine-tuned transformers have different internal activation scales, so a controlnet_conditioning_scale that works on one base produces too-weak or overpowering guidance on another. This node auto-calibrates the CN signal magnitude to match the loaded transformer's hidden-state scale, so cn_target_strength (1.0 = standard) behaves consistently. The manual controlnet_conditioning_scale (default 1.0) is only used when auto-scale is OFF - and the tooltip warns that with custom/fine-tuned transformers, manual values of 10-30 may be needed, which tells you how much auto-scale is doing for you.
Scheduling controls: control_guidance_start/end (fraction of S1 steps CN is active - end early to let the model finish freely), plus s2_cn_scale/s2_cn_start/s2_cn_end for Stage 2 (set s2_cn_scale to 0 to disable CN at refinement).
Everything else is UltraGen
The stage block is identical to UltraGen - s1_mp, s1_steps, s1_cfg, upscale_to_stage2, s2_steps/cfg/denoise/sigma_schedule, s3_*, seed_mode, max_sequence_length, and the optional upscale_vae / upscale_vae_mode for the 2× Wan upscale VAE. Same defaults philosophy: high-CFG low-res draft (here, ControlNet-guided), 4× jump, 26-step refinement at CFG 4, light Karras polish. The negative_prompt ships with the official Chinese Qwen negative pre-filled. Output is image.
Workflow shape and gotchas
The canonical wire-up: Qwen-Image Loader → [Apply LoRA] → [Spectrum] → ControlNet Loader → UltraGen CN → Save. The ControlNet model stays on CPU until called, so it doesn't sit in VRAM between runs - but the generation itself is heavy, and everything said about UltraGen's slowness applies double here (two models in play, plus multi-stage sampling on a 20B base). Draft at low s1_mp with CN active before committing to the full bake.
Two practical notes. First, don't expect pixel-exact map adherence at high resolution - the CN guides composition, and the upscale stages deliberately loosen it (s2_cn_scale defaults to 1.0 but you'll often want it lower, or 0, so refinement doesn't fight the model's detail formation). Second, if the guidance feels completely absent or overwhelming, check whether cn_auto_scale is on before you touch manual scales - the manual rabbit hole is deep and usually unnecessary.
Install: ComfyUI Manager search "Eric Qwen Edit", or git clone https://github.com/EricRollei/Eric_Qwen_Edit_Experiments into custom_nodes/, with the Qwen-Image pipeline loaded upstream and the ~2.3 GB InstantX Union ControlNet downloaded on first load.
Inputs (34)
| Name | Type | Default | Description |
|---|---|---|---|
| pipeline | QWEN_IMAGE_PIPELINE | From the Qwen-Image loader or component loader | |
| controlnet | QWEN_IMAGE_CONTROLNET | From the Qwen-Image ControlNet Loader | |
| control_image | IMAGE | The control/condition image (canny edges, depth map, pose skeleton, or soft edges). Will be fitted to generation dimensions using cn_fit_mode. | |
| cn_fit_mode | COMBO | match_control | How the control image is fitted to generation dimensions: • match_control — override aspect ratio to match control image • crop_center — scale to cover, center crop • crop_top_left/right — crop from corner • crop_bottom_left/right — crop from corner • pad_black_left/right/top/bottom — fit inside, pad with black • pad_edge_left/right/top/bottom — fit inside, extend edges with Gaussian feathering (ideal for depth maps) • stretch — distort to fill (legacy) |
| prompt | STRING | Describe the image you want to generate. For best results, use detailed descriptions (~200 words). Connect a Prompt Rewriter node to auto-enhance short prompts. | |
| negative_promptopt | STRING | 低分辨率，低画质，肢体畸形，手指畸形，画面过饱和，蜡像感，人脸无细节，过度光滑，画面具有AI感。构图混乱。文字模糊，扭曲。 | What to avoid. Default is the official Qwen-Image-2512 negative prompt (Chinese). |
| aspect_ratioopt | COMBO | 1:1 Square | Aspect ratio applied at every stage |
| seedopt | INT | 00–18446744073709550000 | Random seed (0 = random) |
| seed_modeopt | COMBO | offset_per_stage | How seeds are chosen for each stage: • same_all_stages — one generator for all stages • offset_per_stage — S2 uses seed+1, S3 uses seed+2 • random_per_stage — independent random seed per stage |
| max_sequence_lengthopt | INT | 1024128–1024 | Maximum prompt token length for the text encoder. |
| cn_auto_scaleopt | BOOLEAN | true | Auto-calibrate ControlNet strength to match the transformer's internal activation scale. Compensates for custom/finetuned transformers that have different hidden-state magnitudes than the base model the ControlNet was trained on. When enabled, cn_target_strength controls the final CN influence and conditioning_scale is ignored. |
| cn_target_strengthopt | FLOAT | 1.00.1–6 | ControlNet influence strength (auto-scale mode). 1.0 = standard (recommended starting point). 0.5 = subtle structural hints. 1.5–2.0 = strong structural guidance. 3.0+ = very strong (may over-constrain). Internally maps to hidden-state ratio (1.0 = 5%). |
| controlnet_conditioning_scaleopt | FLOAT | 1.00–50 | Manual ControlNet influence strength on Stage 1. Only used when cn_auto_scale is OFF. With custom/finetuned transformers, values of 10–30 may be needed (base model uses 1.0). 0.0 = ControlNet effectively disabled. |
| control_guidance_startopt | FLOAT | 0.000–1 | When ControlNet guidance begins (fraction of S1 steps). 0.0 = from the start (default). |
| control_guidance_endopt | FLOAT | 1.000–1 | When ControlNet guidance ends (fraction of S1 steps). 1.0 = through the end (default). 0.5 = ControlNet guides composition in early steps, then frees up for creative detail in later steps. |
| s2_cn_scaleopt | FLOAT | 1.00–50 | ControlNet influence strength on Stage 2. Only used when cn_auto_scale is OFF. When auto_scale is ON, S2 uses the same auto-calibrated factor as S1 (scaled by this value relative to S1 — e.g. 0.5 = half S1 strength). 0.0 = ControlNet disabled for S2. |
| s2_cn_startopt | FLOAT | 0.000–1 | When ControlNet guidance begins in Stage 2 (fraction of S2 steps). 0.0 = from the start. |
| s2_cn_endopt | FLOAT | 1.000–1 | When ControlNet guidance ends in Stage 2 (fraction of S2 steps). 1.0 = through the end (default). 0.5 = guide structure in early S2 steps only. |
| s1_mpopt | FLOAT | 0.50.3–2 | Stage 1 resolution in megapixels. |
| s1_stepsopt | INT | 151–200 | Stage 1 inference steps (ControlNet-guided txt2img) |
| s1_cfgopt | FLOAT | 10.01–20 | Stage 1 true CFG scale. |
| upscale_to_stage2opt | FLOAT | 4.00–10 | Upscale factor (area) from Stage 1 to Stage 2. Set to 0 to skip Stage 2 & 3 (output Stage 1 only). |
| s2_stepsopt | INT | 261–200 | Stage 2 inference steps (refinement, optional ControlNet). |
| s2_cfgopt | FLOAT | 4.01–20 | Stage 2 true CFG scale. |
| s2_denoiseopt | FLOAT | 0.850.1–1 | Stage 2 denoise strength. |
| s2_sigma_scheduleopt | COMBO | linear | Sigma schedule curve for Stage 2 refinement. |
| upscale_to_stage3opt | FLOAT | 2.00–8 | Upscale factor (area) from Stage 2 to Stage 3. Default 0 = disabled (2-stage output). |
| s3_stepsopt | INT | 181–200 | Stage 3 inference steps |
| s3_cfgopt | FLOAT | 2.01–20 | Stage 3 true CFG scale |
| s3_denoiseopt | FLOAT | 0.450.1–1 | Stage 3 denoise strength. |
| s3_sigma_scheduleopt | COMBO | karras | Sigma schedule curve for Stage 3 final polish. |
| upscale_vaeopt | UPSCALE_VAE | Optional: Wan2.1 2× upscale VAE. Load with Eric Qwen Upscale VAE Loader. | |
| upscale_vae_modeopt | COMBO | both | How the upscale VAE is used (requires upscale_vae). • disabled — upscale VAE ignored • inter_stage — decode S2→2×→re-encode for S3 • final_decode — 2× upscale on final output • both — inter-stage + final decode |
| pad_edge_bluropt | FLOAT | 0.400–1 | Blur strength for pad_edge_* fit modes. Controls how far the Gaussian feather extends into the padding zone. • 0.0 = pure edge replication (may show bands at seam) • 0.4 = default — gentle, natural depth taper • 1.0 = heavy blur, very soft fade Has no effect on pad_black_* or other modes. |
Outputs (1)
| Name | Type | Description |
|---|---|---|
| image | IMAGE | — |