feat(models): add Qwen-Image-2.1 edits from reference images

docs/src/content/docs/Users Guide/03.Models/02.model-families.mdx

@@ -44,15 +44,15 @@ page lists the builds it supports.
 
 InvokeAI recognizes the format from the file's contents, so you install them like any other model. Which format loads for which model is listed in [Model Format Support](/users-guide/models/model-format-support/).
 
-- **GGUF** (`.gguf`, llama.cpp quantization such as Q4_K or Q8_0): weights stay packed in memory and are unpacked layer by layer during generation. Supported for the FLUX.1, FLUX.2, Z-Image, Krea-2, Qwen-Image, Ideogram 4, ERNIE-Image and Wan transformers, and for the T5, Qwen3, Qwen3-VL, Mistral and Gemma 2 text encoders. ComfyUI-GGUF's `Q8_CR` files, which store int8 (`int8_convrot`) layers inside a `.gguf`, load for the Krea-2 transformer; for other models, and for ComfyUI-GGUF's `Q4_CR`, installation is refused with a message saying so.
+- **GGUF** (`.gguf`, llama.cpp quantization such as Q4_K or Q8_0): weights stay packed in memory and are unpacked layer by layer during generation. Supported for the FLUX.1, FLUX.2, Z-Image, Krea-2, Qwen-Image, Qwen-Image-2.1, Ideogram 4, ERNIE-Image and Wan transformers, and for the T5, Qwen3, Qwen3-VL, Mistral and Gemma 2 text encoders. ComfyUI-GGUF's `Q8_CR` files, which store int8 (`int8_convrot`) layers inside a `.gguf`, load for the Krea-2 transformer; for other models, and for ComfyUI-GGUF's `Q4_CR`, installation is refused with a message saying so.
 - **NF4** (bitsandbytes): 4-bit, CUDA only.
 - **SDNQ**: see [SDNQ Quantization](/configuration/optimization/sdnq-quantization/).
-- **int8** (`int8_convrot`, from ComfyUI repackages): the weights stay int8 in memory on every device, including Apple Silicon, and need no setting to turn on. Supported for FLUX.1, FLUX.2 Klein, Z-Image, Krea-2, Ideogram 4, MiniMax H3, LTX-2 and the PiD decoders, and for the Qwen3 8B, Qwen3-VL and LTX-2 Gemma encoders.
-- **nvfp4** (4-bit, in ComfyUI's checkpoint format, such as Comfy-Org's builds; other nvfp4 exports such as AWQ are refused): the weights stay packed in memory and are unpacked per layer, so no special GPU is needed. Supported for the Z-Image, Krea-2, Qwen-Image and LTX-2 transformers and for the Qwen3, Qwen2.5-VL and FLUX.2 Mistral encoders; the Ideogram 4 nvfp4 files are refused at install.
+- **int8** (`int8_convrot`, from ComfyUI repackages): the weights stay int8 in memory on every device, including Apple Silicon, and need no setting to turn on. Supported for FLUX.1, FLUX.2 Klein, Z-Image, Krea-2, Qwen-Image-2.1, Ideogram 4, MiniMax H3, LTX-2 and the PiD decoders, and for the Qwen3 8B, Qwen3-VL and LTX-2 Gemma encoders.
+- **nvfp4** (4-bit, in ComfyUI's checkpoint format, such as Comfy-Org's builds; other nvfp4 exports such as AWQ are refused): the weights stay packed in memory and are unpacked per layer, so no special GPU is needed. Supported for the Z-Image, Krea-2, Qwen-Image and LTX-2 transformers and for the Qwen3, Qwen2.5-VL and FLUX.2 Mistral encoders; the Ideogram 4 and Qwen-Image-2.1 nvfp4 files are refused at install.
 - **fp8** (plain or `fp8_scaled`): InvokeAI keeps the weights in fp8 when [FP8 Storage](/configuration/optimization/fp8-storage/) is on, which installation does for you, or when `fp8_compute` is enabled.
 - **MXFP8** (fp8 with one scale per block of 32 weights): loaded by unpacking to BF16. Turn FP8 Storage off for these; see the [FP8 Storage caution](/configuration/optimization/fp8-storage/).
 
-Text encoders for Qwen-Image, Z-Image, Krea-2 and Ideogram 4 bring their tokenizer and configuration with InvokeAI, so single-file and GGUF encoders load without network access.
+Text encoders for Qwen-Image, Z-Image, Krea-2, Ideogram 4 and Qwen-Image-2.1 bring their tokenizer and configuration with InvokeAI, so single-file and GGUF encoders load without network access.
 
 ### Converting to Diffusers
 
@@ -78,7 +78,8 @@ yourself. They appear as separate models in the Model Manager, and
 generation panels show slots for them (for example **VAE**, **Text
 encoder** or **Model components**) when the selected model needs
 them. Several families share components: FLUX.2 and Ideogram 4 use
-the same VAE, for example, so one download can serve both.
+the same VAE, for example, and Ideogram 4 and Qwen-Image-2.1 the same Qwen3-VL 8B
+encoder, so one download can serve both.
 
 | Component | What it does |
 |---|---|
@@ -122,6 +123,7 @@ faster generation.
 | **Z-Image** | Images | 6B model in a fast, few-step Turbo variant and a Base variant. Understands English and Chinese prompts, with ControlNets. | Apache 2.0 | [Z-Image](/users-guide/models/local-models/z-image/)  |
 | **ERNIE-Image** | Images | Baidu's 8B text-to-image model, in standard and distilled Turbo variants. | Apache 2.0 | [ERNIE-Image](/users-guide/models/local-models/ernie-image/)  |
 | **Qwen Image** | Images | Text-to-image (2512) and instruction-based image editing (Edit 2511), with fast Lightning variants. | Apache 2.0 | [Qwen Image](/users-guide/models/local-models/qwen-image/)  |
+| **Qwen-Image-2.1** | Images | 7B text-to-image model with strong text rendering and transparent (RGBA) output, in a base and an 8-step Turbo variant. Edits from reference images. | Non-commercial | [Qwen-Image-2.1](/users-guide/models/local-models/qwen-image-2-1/)  |
 | **Krea-2** | Images | 12B model in fast Turbo and undistilled Raw variants, with training-free style reference. | Community, free under $1M revenue | [Krea-2](/users-guide/models/local-models/krea-2/)  |
 | **Ideogram 4** | Images | Structured prompts that place described elements in regions of the image. | Non-commercial | [Ideogram 4](/users-guide/models/local-models/ideogram4/)  |
 | **Anima** | Images | Compact 2B anime-focused model, with ControlNet-LLLite adapters for inpainting and sketch guidance. | Non-commercial | [Anima](/users-guide/models/local-models/anima/)  |

docs/src/content/docs/Users Guide/03.Models/03.model-format-support.mdx

@@ -1,7 +1,7 @@
 ---
 title: Model Format Support
 description: Which file formats and quantizations InvokeAI loads for every model family, text encoder, VAE and adapter.
-lastUpdated: 2026-10-11
+lastUpdated: 2026-10-16
 sidebar:
   order: 3
 ---
@@ -34,6 +34,7 @@ Ministral 3B encoder. Others are recognized by their layer names and fail, or mi
 | [CogView4](/users-guide/models/local-models/cogview4/) | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
 | [Z-Image](/users-guide/models/local-models/z-image/) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ |
 | [Qwen-Image](/users-guide/models/local-models/qwen-image/) | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ |
+| [Qwen-Image-2.1](/users-guide/models/local-models/qwen-image-2-1/) | ✓ | ✓ | ✓ | ✓ | R | – | ✓ | ✗ | ✗ |
 | [Anima](/users-guide/models/local-models/anima/) | – | ✓ | ✓ | ✓ | ✗ | ✓ | ✗ | ✗ | ✗ |
 | [Krea-2](/users-guide/models/local-models/krea-2/) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ |
 | [Ideogram 4](/users-guide/models/local-models/ideogram4/) | ✓ | ✓ | ✓ | ✓ | R | ✓ | ✓ | ✗ | inside the Diffusers folder |
@@ -43,7 +44,8 @@ Ministral 3B encoder. Others are recognized by their layer names and fail, or mi
 | [MiniMax H3](/users-guide/video-generation/minimax-h3/) | ✓ | ✓ | L | ✓ | L | ✗ | ✗ | ✗ | ✗ |
 
 - **int8** means ComfyUI's `int8_convrot` (`int8_tensorwise`) builds. **nvfp4** and **fp8 scaled** mean ComfyUI's
-  checkpoint layouts; other exports of the same schemes (AWQ, ModelOpt) fail when the model loads.
+  checkpoint layouts; other exports of the same schemes (AWQ, ModelOpt) fail when the model loads. For Qwen-Image-2.1,
+  torchao exports such as unsloth's FP8 build are refused at install.
 - **GGUF** covers the llama.cpp types (Q4_0 through Q8_0, the K-quants, BF16). ComfyUI-GGUF's `Q8_CR` files load
   for Krea-2 only; for every other model with GGUF support the install fails.
 - LTX-2.0/2.3 files fail to install with a message. Wan 2.1, Wan Animate, S2V, Fun-Control and VACE single files and
@@ -57,7 +59,7 @@ Ministral 3B encoder. Others are recognized by their layer names and fail, or mi
 | T5-XXL | FLUX.1, SD 3 | ✓ | ✗ | ✗ | ✗ | ✗ | ✓ | ✓ (and bitsandbytes int8) |
 | CLIP-L / CLIP-G | SD, SDXL, FLUX.1, SD 3 | ✓ | ✓ | R | R | – | ✗ | CLIP-L inside a FLUX.1 SDNQ pipeline |
 | Qwen3 0.6B / 4B / 8B | Z-Image, FLUX.2 Klein, Anima | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Qwen3-VL 4B / 8B | Krea-2, Ideogram 4 | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ | ✗ |
+| Qwen3-VL 4B / 8B | Krea-2, Ideogram 4, Qwen-Image-2.1 (8B) | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ | ✗ |
 | Qwen3-VL 32B (truncated) | MiniMax H3 | in the Diffusers folder | ✓ | L | ✓ | L | ✗ | ✗ |
 | Qwen3.5 4B | Anima 3.8B | ✗ | ✓ | L | L | L | ✗ | ✗ |
 | Qwen2.5-VL | Qwen-Image | ✓ | ✓ | ✓ | L | ✓ | ✗ | ✗ |
@@ -85,10 +87,11 @@ not recognized.
 | SD 2.x | ✓ | ✗ | SD 2.x |
 | Wan (16 and 48 channels) | ✓ | ✓ | Wan 2.2; the Wan 2.1 VAE also by Anima |
 | Qwen-Image | ✓ | ✗ | Qwen-Image, Krea-2 |
+| Qwen-Image-2.1 | ✓ | ✓ | Qwen-Image-2.1 |
 | CogView4, LTX-2, MiniMax H3 | – | bundled | taken from the model's own folder |
 
 Quantized VAE files (fp8, int8, nvfp4) are not supported; use the unquantized VAE. The SD 3, FLUX.2, Qwen-Image,
-Wan, Anima and Ideogram 4 VAEs fail with a message when they load. The FLUX.1 and SD 1.x / SDXL single-file VAEs do
+Qwen-Image-2.1, Wan, Anima and Ideogram 4 VAEs fail with a message when they load. The FLUX.1 and SD 1.x / SDXL single-file VAEs do
 not check, so a quantized file there fails with an unclear error or decodes incorrectly.
 
 ## LoRAs and adapters
@@ -101,7 +104,7 @@ not check, so a quantized file there fails with an unclear error or decodes inco
 | FLUX.2, Z-Image | ✓ (LyCORIS, Diffusers) | Z-Image only | |
 | Qwen-Image, Krea-2, Wan 2.2, Anima | ✓ (LyCORIS/kohya, including LoKR where noted on the family page) | Anima (ControlNet-LLLite) | |
 | LTX-2, MiniMax H3 | ✓ (plain low-rank; LoKR, LoHA and DoRA are refused) | ✗ | |
-| SD 3, CogView4, Ideogram 4, ERNIE-Image | ✗ | ✗ | |
+| SD 3, CogView4, Ideogram 4, ERNIE-Image, Qwen-Image-2.1 | ✗ | ✗ | |
 
 [PiD decoders](/users-guide/image-generation/advanced-topics/pid-decode/) load for FLUX.1, FLUX.2, SD 3, SDXL and
 Qwen-Image (v1 and v1.5, bf16 and int8 builds).

docs/src/content/docs/Users Guide/03.Models/Local Models/qwen-image-2-1.mdx

@@ -0,0 +1,80 @@
+---
+title: Qwen-Image-2.1
+description: Generate images with Qwen-Image-2.1 and its 8-step Turbo variant, from the Diffusers folders or a GGUF transformer, including transparent (RGBA) output.
+lastUpdated: 2026-10-16
+sidebar:
+  order: 8
+---
+## Qwen-Image-2.1
+
+Qwen-Image-2.1 is a 7B text-to-image model from the Qwen team with strong text rendering. It is a different model from [Qwen Image](/users-guide/models/local-models/qwen-image/) (2512 and Edit 2511), not an update you can swap in: it encodes prompts with the **Qwen3-VL 8B** model, the same encoder [Ideogram 4](/users-guide/models/local-models/ideogram4/) uses, and decodes with its own 64-channel VAE, which can produce images with a transparent background.
+
+Two variants are available, and the variant is detected on install:
+
+- **Qwen-Image-2.1** — the base model. 40 steps by default.
+- **Qwen-Image-2.1 Turbo** — distilled for 8 steps on a fixed schedule of its own.
+
+Text-to-image, image-to-image, inpainting and outpainting on the Canvas are supported, and with the Diffusers models also edits from [reference images](#reference-images). LoRAs and regional guidance are not supported yet.
+
+### License
+
+Qwen-Image-2.1 is released under the **Qwen Research License**, which allows use for research and evaluation only. Commercial use needs a separate license from Alibaba's Tongyi Lab. The same license covers the Comfy-Org and community repackages of the weights.
+
+This is a summary, not legal advice. Read the full license on the model's HuggingFace page before using a model commercially.
+
+### Installing Qwen-Image-2.1
+
+The starter models install the complete Diffusers folders, which carry the transformer, the VAE and the Qwen3-VL 8B encoder:
+
+- [`Qwen/Qwen-Image-2.1`](https://huggingface.co/Qwen/Qwen-Image-2.1) — the base model, ~31 GB.
+- [`Qwen/Qwen-Image-2.1-Turbo`](https://huggingface.co/Qwen/Qwen-Image-2.1-Turbo) — the Turbo variant, ~30 GB.
+
+You can also paste either repo ID into the Model Manager's HuggingFace / URL field.
+
+#### GGUF and single files
+
+A GGUF or single-file transformer carries only the transformer. Pick the other two parts in the **Components** section next to the model; until both are set, the Invoke button tells you which one is missing:
+
+- **VAE** — the Qwen-Image-2.1 VAE, from Comfy-Org's [`vae/qwen_image_2.1_vae_bf16.safetensors`](https://huggingface.co/Comfy-Org/Qwen-Image-2.1) or the `vae` folder of a Diffusers download. The VAEs of Qwen Image, Wan and FLUX do not fit and are not offered.
+- **Qwen3-VL Encoder** — the Qwen3-VL **8B** encoder, for example the **Qwen3-VL 8B Encoder** starter model, which Ideogram 4 uses as well. The 4B encoder Krea-2 uses does not work and is not offered. A llama.cpp GGUF of the 8B encoder works too; see [Qwen3-VL GGUF encoders](/users-guide/models/local-models/krea-2/#qwen3-vl-gguf-encoders).
+
+The **Qwen-Image-2.1 (Q4_K_M GGUF)** starter model, from [`unsloth/Qwen-Image-2.1-GGUF`](https://huggingface.co/unsloth/Qwen-Image-2.1-GGUF), installs the VAE and the 8B encoder with it, ~15 GB in all. Other quantization levels from that repository load the same way.
+
+Single-file transformers in bf16, scaled fp8 or `int8_convrot` (ComfyUI repackages) load as well. nvfp4 files, torchao-quantized files (such as unsloth's FP8 build), and int8 files without ComfyUI's `int8_convrot` marker, are refused at install. GGUF files with int8 layers (ComfyUI-GGUF's `Q8_CR`) are refused too.
+
+The Turbo variant is recognized from the filename: a single file or GGUF whose name contains `turbo` installs as Turbo, anything else as the base model. If a file was detected as the wrong variant, edit the model in the Model Manager and change its **Variant**. The default settings were chosen at install, so also set **Steps** under **Default Settings**: 8 for Turbo, 40 for the base model.
+
+### Memory and speed
+
+Measured on an RTX 4090 at 1024×1024:
+
+| Transformer | Resident | Time per image |
+|---|---|---|
+| bf16 (Diffusers) | 13.9 GB during denoising | 0.62 s per step, about 25 s for 40 steps |
+| GGUF Q4_K_M | 4.0 GB | about 40 s for 40 steps |
+
+The text encoder runs first and is unloaded from the GPU when the transformer needs the room. At 2048×2048 the bf16 transformer needs 15.5 GB and 3.7 s per step.
+
+The VAE needs about 8 GB of working memory to decode a 1024×1024 image, and is priced the same to encode one for image-to-image, inpainting or outpainting (twice that with `precision: float32`). When an image is too large for the card to handle in one piece, Invoke decodes and encodes it in tiles; see [Large decodes](/configuration/optimization/low-vram-mode/). Invoke picks 1024-pixel tiles, and 768 or 512 only on cards with less memory: measured at 2048×2048, 1024-pixel tiles came close to an untiled decode (47.7 dB PSNR), while the 256-pixel tiles other VAEs default to left visible seams (35.6 dB).
+
+### Reference images
+
+With a Qwen-Image-2.1 **Diffusers** model, add up to four images with **Add reference image** in the Guidance section (see [Adding reference images](/users-guide/image-generation/generate-panel/#adding-reference-images)) and say in the prompt what to do with them, for example *put the jacket from the first image on the person in the second* or *the same cat, as a watercolor*. The model reads each reference twice: its Qwen3-VL encoder looks at it alongside the prompt, and the transformer sees it as clean latents next to the image it generates.
+
+- **Diffusers models only.** Only the encoder that comes with the Diffusers model keeps the Qwen3-VL vision tower, which reads the images. A single-file or GGUF transformer with a standalone encoder does not offer reference images, and on a Diffusers model the references refuse to run while a standalone **Qwen3-VL Encoder** is selected under **Components**; clear it to edit.
+- **Size.** Each reference is read at about one megapixel at its own aspect ratio, whatever its size. The generated image takes the size set in the panel; **Use size** on a reference's thumbnail matches it.
+- **Transparency.** The encoder sees a transparent reference over white, as the model was trained; its latents keep the transparency.
+- **Memory.** The vision tower adds about 1.1 GB to the Diffusers model's encoder, on every generation with it. Each reference adds about 4,100 tokens to the start of the sequence, which the model keeps for the whole generation: about 2 GB per reference, twice that with **CFG** above 1. Where that would take more than half of the GPU, Invoke reprocesses the references at every step instead of keeping them, which uses less memory but takes noticeably longer. Reading the references also needs encoder memory that grows quickly with their number: about 7 GB beyond its weights for four, so on a 24 GB card part of the encoder then runs from system memory.
+
+### Transparent images
+
+The Qwen-Image-2.1 VAE decodes an alpha channel along with the colors, so a prompt such as *a sticker of a red fox on a transparent background* produces a cut-out image. An image is saved with transparency only when it has some: when more than 0.1% of its pixels are noticeably transparent. Opaque images are saved as ordinary RGB, so the faint edges tiled decoding leaves in the alpha channel never turn an opaque image transparent.
+
+Image-to-image, inpainting and outpainting read the colors of the input image and treat it as fully opaque, whatever its alpha channel holds.
+
+### Generation settings
+
+- **Steps** — 40 for the base model and 8 for Turbo. Turbo's schedule is tuned for 8 steps; other step counts are spread over the same curve and work, but 8 is what it was distilled for.
+- **CFG** — 1 by default, which runs one prompt per step. Above 1, the negative prompt is used and each step costs about twice as long.
+- There is no scheduler setting: both variants use the schedule they were trained with.
+- **Denoising strength** (image-to-image, inpainting) — on the base model a strength changes the image about as much as on Qwen-Image or Z-Image. Turbo's 8-step schedule spends most of its steps at high noise, so there a strength sets the starting noise level directly (0.5 starts at noise level 0.5): the same value changes the image less on Turbo than on the base model.