TwinFlow Z-Image Loader (core)

You probably saw someone claim Z-Image Turbo generates in one or two steps and went looking for the checkpoint. Good news: the TwinFlow re-training works on Z-Image Turbo. Bad news: it's a modified checkpoint with an extra set of weights, and stock ComfyUI's loader will either choke on it or quietly drop them.

What TwinFlow actually is

Z-Image Turbo already runs in 8 steps because Alibaba distilled it. TwinFlow (arXiv 2512.05150, inclusionAI) pushes the same trick further with a self-adversarial flow objective - the model rectifies its own flow field instead of leaning on a separate teacher or discriminator, which is what makes 20B-scale full-parameter training affordable. The result wants 2 to 4 NFEs at CFG 1 instead of 8.

The wrinkle is architectural: TwinFlow's model carries a t_embedder_2 that stock Z-Image lacks, injecting a delta between the current timestep and a target timestep into the AdaLN modulation. No extra embedder, no TwinFlow.

How this node works

Nothing exotic happens at the ComfyUI level. It reads the file with comfy.utils.load_torch_file, pops the t_embedder_2.* tensors out before the rest goes to load_diffusion_model_state_dict (core's diffusers-name conversion eats those keys otherwise), lets ComfyUI build a normal Z-Image/NextDiT model, then grafts the small embedder onto diffusion_model.t_embedder and wraps the original so it adds the delta term when the sampler supplies one.

The target timestep rides in through the standard transformer_options channel and the TwinFlow sampler is a plain comfy.samplers.KSAMPLER, so CFG, hooks, LoRAs and patches all keep working. requirements.txt is empty of extras: no diffusers, no new pip deps.

The two inputs, and the one output

model_name is a dropdown of everything in ComfyUI/models/diffusion_models - nothing else, not models/gguf, not checkpoints. If your TwinFlow file isn't showing up, it's in the wrong folder.

weight_dtype is a load-time cast: default (whatever's in the file), fp8_e4m3fn, fp8_e4m3fn_fast, fp8_e5m2. Pick fp8_e4m3fn if a BF16 checkpoint is blowing your VRAM budget - half the weight footprint, and the quality cost is close to invisible. fp8_e4m3fn_fast also turns on ComfyUI's fp8 optimizations, which pay off mainly with --fast on a 40-series or newer card.

The single output is model (MODEL), which goes into a SamplerCustom's model slot (or a plain KSampler, though the example workflow uses SamplerCustom).

Two things it does not do, and people get burned on both:

• It doesn't sample. You still need TwinFlow_Sampler_Select from the same pack on the sampler input. Feeding this model into a stock Euler sampler is the most common reason for muddy output.
• It doesn't load CLIP or VAE. Use stock CLIPLoader with qwen_3_4b.safetensors at type lumina2, plus the Flux VAE (ae.safetensors) in models/vae.

One quirk: the TwinFlow sampler discards your sigmas and builds its own schedule, but counts them first to set the NFE - the steps widget still works, the sigma values don't.

Install

ComfyUI Manager → search "TwinFlow" → install → restart. If Manager won't take it, clone it:

cd ComfyUI/custom_nodes
git clone https://github.com/smthemex/ComfyUI_TwinFlow
# restart ComfyUI

Manual cloning is a real fix here, not a fallback - early adopters reported Manager refusing the pack outright.

Then get the weights. The TwinFlow Z-Image checkpoint (BF16, Q8_0, or the int8 convrot build) goes in models/diffusion_models, CLIP and VAE from Comfy-Org's z_image_turbo split files:

ls ComfyUI/models/diffusion_models | grep -i twinflow

That same repo also hosts GGUF builds, and here's the trap: this loader has no GGUF branch - it globs diffusion_models and calls the standard torch loader. The GGUF path in this pack belongs to the Qwen-Image loader, which needs the separate ComfyUI_Dif_GGUF plugin. For Z-Image, grab a safetensors build.

Common issues

[TwinFlow] 't_embedder_2.mlp.0.weight' not found in checkpoint - you pointed it at plain Z-Image Turbo; stock Z-Image has no t_embedder_2, so the node refuses rather than producing noise. Download the TwinFlow re-training, not the Tongyi-MAI original. ("comfy could not detect this checkpoint as a diffusion model" means the file is truncated or not a DiT at all.)

Nodes missing from the menu entirely - the pack registers as a ComfyUI V3 extension (comfy_api.latest, comfy_entrypoint), so a ComfyUI install older than that API won't see any of the three nodes. Update ComfyUI, restart.

Oversaturated, artifacted, or plain bad output - three suspects in order: no TwinFlow sampler, CFG above 1, or too few steps. Set CFG to 1.0 - the official config wants guidance off entirely, and with one or two model calls there are no later steps to absorb the distortion. Then be honest about step count: community testing settled on 4 steps for decent quality, and more than one person concluded 2-step TwinFlow isn't visibly better than stock Z-Image Turbo at the same count. It buys steps, not magic.

The author flags this node is_experimental: when something breaks after a ComfyUI update, check the pack's repo before reinstalling torch.