# Z-Image

Z-Image is a 6B-parameter text-to-image family from Tongyi-MAI that understands both English and Chinese
prompts. It encodes prompts with a **Qwen3 4B** text encoder and decodes with the same 16-channel VAE as
FLUX.1. InvokeAI supports two variants:

- **Z-Image Turbo** is distilled for fast, low-step generation with **CFG disabled** (CFG Scale `1.0`).
  This is the checkpoint the starter models install.
- **Z-Image Base** is the undistilled foundation model. It needs more steps, and supports CFG and negative
  prompts.

A Diffusers pipeline's variant is detected on install. Single-file, GGUF and SDNQ files are registered as
**Turbo**. If you install a Base checkpoint in one of those formats, change its **Variant** to *Z-Image
Base* in the Model Manager so the right defaults and schedulers apply.

Z-Image works in the Generate tab, on the Canvas (text-to-image, image-to-image, inpainting and
outpainting) and in the workflow editor.

## License

Z-Image Turbo, Z-Image (Base) and their Qwen3 text encoder are released under **Apache 2.0**, which allows commercial use. None of the downloads is gated.

This is a summary, not legal advice. Read the full license on the model's HuggingFace page before using a model commercially.

## Hardware

See the [System Requirements](/start-here/system-requirements/) table. In short: a Q4_K GGUF or NVFP4
transformer runs in about 8 GB of VRAM, while the Q8 and full-precision (BF16) builds want 16 GB or more.
The full Diffusers pipeline is roughly a 33 GB download.

For more headroom you can enable [FP8 Storage](/configuration/optimization/fp8-storage/) on a
full-precision Z-Image model, use an [SDNQ](/configuration/optimization/sdnq-quantization/) build, or turn
on [Low-VRAM mode](/configuration/optimization/low-vram-mode/).

## Installing

The easiest path is the **Z-Image** bundle in the Model Manager. It installs the Z-Image Turbo Q4_K GGUF
transformer, the quantized Qwen3 encoder, the FLUX VAE and both Z-Image ControlNets.

Z-Image needs three components:

| Component             | Diffusers / SDNQ pipeline | GGUF / single-file install           |
| --------------------- | ------------------------- | ------------------------------------ |
| Transformer           | bundled                   | the `.gguf` / `.safetensors` file    |
| Text encoder (Qwen3 4B) | bundled                 | installed separately                 |
| VAE (FLUX.1)          | bundled                   | installed separately (any FLUX VAE)  |

The starter models:

| Starter                            | Format                      | Size    | Also installs                                  |
| ---------------------------------- | --------------------------- | ------- | ---------------------------------------------- |
| Z-Image Turbo                      | Diffusers pipeline          | ~33 GB  | nothing, everything is bundled                 |
| Z-Image Turbo (quantized)          | GGUF Q4_K                   | ~4 GB   | Qwen3 encoder (GGUF Q6_K, ~3.3 GB) + FLUX VAE  |
| Z-Image Turbo (Q8)                 | GGUF Q8_0                   | ~6.6 GB | Qwen3 encoder (GGUF Q6_K) + FLUX VAE           |
| Z-Image Turbo (NVFP4)              | Comfy-Org nvfp4 single file | ~4.5 GB | Qwen3 encoder (FP4 mixed, ~3.5 GB) + FLUX VAE  |
| Z-Image Turbo (fp8)                | Kijai scaled fp8 single file | ~6.2 GB | Qwen3 encoder (FP4 mixed, ~3.5 GB) + FLUX VAE  |
| Z-Image Turbo (int8)               | Comfy-Org int8 single file  | ~6.2 GB | Qwen3 encoder (FP4 mixed, ~3.5 GB) + FLUX VAE  |
| Z-Image Turbo (SDNQ uint4 + SVD)   | SDNQ Diffusers pipeline     | ~5 GB   | nothing, everything is bundled                 |

A full-precision **Z-Image Qwen3 Text Encoder** (~8 GB) and its community **int8** build (~4.4 GB download,
about 4.4 GB once loaded) are also available as separate starters.

The NVFP4 build keeps its quantized layers packed in memory and decodes them on the fly, so it needs about
a third of the full-precision transformer's memory. The int8 build keeps its int8 layers as well, about 6.2 GB
once loaded on every supported GPU, and [int8 Compute](/configuration/optimization/int8-compute/) can run
them on NVIDIA int8 tensor cores.

### Choosing components

When the selected Z-Image model is not a self-contained pipeline, the **Components** section next to the
model shows three slots:

- **Component source**: a Diffusers (or SDNQ) Z-Image pipeline to borrow the encoder and VAE from.
- **Qwen3 Encoder**: a standalone Qwen3 4B encoder. Only 4B encoders are listed: the Qwen3 8B encoder that
  FLUX.2 Klein 9B uses is too wide for Z-Image. A project that still has an 8B encoder selected shows it in the
  slot with an error, and Invoke stays unavailable until you pick a 4B encoder or clear the slot. In a
  workflow, **Main Model - Z-Image** refuses any other Qwen3 encoder by name when it runs.
- **VAE**: Z-Image decodes with the FLUX VAE, so FLUX-base VAEs are listed here.

You need either a component source or both a Qwen3 encoder and a VAE before you can generate.

## Generation settings

Selecting a Z-Image model applies these defaults:

| Variant       | Steps | CFG Scale | Scheduler | Size      |
| ------------- | ----- | --------- | --------- | --------- |
| Z-Image Turbo | 9     | 1.0       | Euler     | 1024×1024 |
| Z-Image Base  | 50    | 4.0       | Euler     | 1024×1024 |

- **CFG Scale**: `1.0` turns CFG off, which is what Turbo is trained for. Values below `1.0` are not
  accepted.
- **Negative prompt**: only used when CFG Scale is above `1.0`. With Turbo at `1.0` it has no effect.
- **Schedulers**: *Euler* (the default and recommended), *Heun (2nd order)* (better quality, about twice as
  slow) and *LCM*. LCM works with Turbo only and is not offered for Z-Image Base.
- **Resolution**: width and height must be multiples of 16.
- **Prompt weighting**: Compel-style [prompt syntax](/users-guide/image-generation/advanced-prompt-syntax/#attention-weighting) does not
  apply to Z-Image. Write prompts in plain language.

- **Shift**: the Render section's **Shift** override fixes the timestep shift of the sampling schedule.
  Leave the override off to have it calculated from the image size, which is the recommended setting; the
  override starts at `3`. In the workflow editor the same thing is the **Shift** input of **Denoise - Z-Image**.

## ControlNet

Two Z-Image ControlNets are available as starters (both are part of the bundle):

- **Z-Image ControlNet Union** handles Canny, HED, Depth, Pose and MLSD control images.
- **Z-Image ControlNet Tile** is useful for upscaling and adding detail. The **Upscale** tool can use it as an
  optional anchor; see [Upscaling](/users-guide/image-generation/upscale/).

Every Z-Image Turbo Fun-ControlNet alibaba-pai has published can be installed from its `.safetensors` file:
the first Union release, Union 2.0, the Union and Tile 2.1 builds (8-step, 2601 and 2602 included) and the 2.1
Lite builds. Invoke tells them apart by their weights. Invoke does not inpaint through a Z-Image ControlNet:
a control layer takes a control image only.

On the Canvas, add a **Control Layer** while a Z-Image model is selected. The layer uses a Z-Image
ControlNet with a default weight of `0.75`. The weight ranges from `0` to `2`, and `0.65` to `0.80` is the
recommended range. **Only one** Z-Image control layer can be used per generation.

Earlier Invoke versions placed the hints of the Lite and first Union builds after the wrong layers, and left
out the refiner hints of 2.0 and 2.1 (2.0 also refined its control through the wrong blocks). Applied as they were trained, these ControlNets now follow the control image
more strongly at the same weight; lower the weight if a control image constrains the result too much.

In the workflow editor, the same thing is the **Z-Image ControlNet** node feeding the **Control** input of
**Denoise - Z-Image**. That node also needs the **VAE** input connected, which it uses to encode the
control image.

## Regional prompting

Z-Image supports **Regional Guidance** layers on the Canvas with positive and negative prompts, together with
a control layer if you like. The global positive prompt covers the area outside the regions, while the global
negative prompt applies to the whole image. **Auto-Negative** uses the region's positive prompt as a negative
outside its mask. Regional negatives and auto-negative take effect only when **CFG Scale** is above 1; Turbo's
default CFG 1 ignores them. Regional reference images are not supported.

In the workflow editor, **Prompt - Z-Image** takes an optional mask, and **Denoise - Z-Image** accepts
either one conditioning or a collection of them.

## LoRA

Z-Image LoRAs are supported in Kohya, PEFT/Diffusers and LyCORIS formats. They are applied to both the
transformer and the Qwen3 encoder. In the workflow editor, use **Apply LoRA - Z-Image** or **Apply LoRA
Collection - Z-Image**.

## Seed Variance Enhancer

Z-Image Turbo tends to produce similar images across different seeds. **Seed variance**, next to the seed
in the Generate panel's Render section, adds reproducible, seed-based noise to the prompt conditioning to
increase variety:

- **Variance strength**: `0` is off, `0.1` (the default) is subtle, `0.5` is strong.
- **Randomized channels**: the share of embedding values that receive noise (default `50%`).

Both settings are recorded in image metadata and restored by Recall All. In the workflow editor the same
thing is the **Seed Variance Enhancer - Z-Image** node, connected between **Prompt - Z-Image** and the
denoise node's positive conditioning.

## PiD decoding

Z-Image has no PiD decoder of its own and uses the **FLUX** PiD decoders, since it shares FLUX.1's VAE. See
[PiD Decode](/users-guide/image-generation/advanced-topics/pid-decode/).