LightVAE

LightVAE

Swaps in lighter video autoencoder parts for Wan2.1, Wan2.2 and MiniMax-H3, through a ComfyUI node or a Python script. For video AI users who want compact VAE components.

Made by lightx2v on Hugging Face. These notes are Mindket's, written from its model page and model card; the model's own files and license are on Hugging Face.

About

What it is: LightVAE shrinks the video autoencoders used by Wan2.1, Wan2.2 and MiniMax-H3. The smaller parts keep the same latent interface as the originals, so you can mix a compact part with an original one. For Wan models you get Pro and Lite decoders, and for MiniMax-H3 you get a Lite encoder and decoder plus an optional INT8 decoder for ComfyUI.

Who it suits: People who run Wan or MiniMax-H3 video models and want compact VAE parts, in ComfyUI or in a plain Python script.

Industry | Who uses it | How they use it | Example
Video generation | ComfyUI users | Swap a lighter decoder or encoder into a MiniMax-H3 workflow | Use the Load H3 LightVAE node in a first and last frame workflow
AI infrastructure | Inference engineers | Pair compressed VAE parts with the original backbone | An original Wan2.1 encoder with a Lite decoder
Research | Video model researchers | Test pruned and low-rank autoencoders by reconstructing clips | Rebuild a demo video with the infer script
Creative studios | Pipeline builders | Try the INT8 decoder inside ComfyUI | Decode H3 output with the quantized file

You can skip it if you do not use Wan2.1, Wan2.2 or MiniMax-H3, since the parts are matched to those backbones.

Where to use it: ComfyUI covers MiniMax-H3, and standalone Python scripts cover the Wan reconstruction example.

• ComfyUI, in a version with native MiniMax-H3 support
• Standalone Python scripts, using infer.py
• Windows, macOS or Linux with Python, to download the files

Use case | Who | What they get back
Lighter H3 decoding | ComfyUI users | A Lite encoder or decoder in the H3 video workflow
Wan reconstruction | Researchers | A reconstructed video file made with the original Wan2.1 encoder and a Lite decoder
INT8 decoding | ComfyUI users | A quantized H3 Lite decoder, for ComfyUI only

How to set it up: For ComfyUI, add the LightVAE code, run its installer, then download the Lite files. The Python path needs the code, its requirements and the original Wan VAE.

• ComfyUI with native MiniMax-H3 support, and the Python environment that starts it
• The original H3 video VAE
• For the optional INT8 decoder, a PyTorch build for CUDA 13.0 or newer and a compatible driver

1. Get the LightVAE code from GitHub into your ComfyUI folder, and never clone it straight into custom_nodes.
2. Run the installer script, which creates the custom node folder for you.
3. Download the Lite H3 encoder and decoder files.
4. Download the original H3 video VAE if you do not have it.
5. Restart ComfyUI and search for the Load H3 LightVAE node.

cd /path/to/ComfyUI

python LightVAE/comfyui/install.py --comfy-root .

python -m pip install huggingface_hub
hf download lightx2v/LightVAE \
  lightvae-lite-h3-decoder.safetensors \
  lightvae-lite-h3-encoder.safetensors \
  --local-dir models/vae/LightVAE

hf download Comfy-Org/MiniMax-H3 \
  vae/minimax_h3_video_vae_fp16.safetensors \
  --local-dir models

How to use it: In ComfyUI, load the original H3 video VAE through the regular Load VAE node and wire its output into the base_vae input. Then pick the Lite parts inside Load H3 LightVAE, and load one of the three workflow files into ComfyUI.

• First and last frame workflows: replace only the decoder, and leave encoder set to none.
• Reference workflows: replace the encoder, the decoder or both.
• Setting none: use the matching original part.

For the Python route, download the Lite Wan2.1 decoder and the original Wan2.1 VAE, then run the infer script from the LightVAE folder.

python -m pip install -r requirements.txt

hf download lightx2v/LightVAE \
  lightvae-lite-wan21-decoder.safetensors \
  --local-dir weights/LightVAE

hf download Wan-AI/Wan2.1-T2V-1.3B \
  Wan2.1_VAE.pth --local-dir weights/Wan2.1

python infer.py \
  --model wan21 --variant lite \
  --encoder weights/Wan2.1/Wan2.1_VAE.pth \
  --decoder weights/LightVAE/lightvae-lite-wan21-decoder.safetensors \
  --input demo.mp4 --frames 81 --height 480 --width 832 \
  --output outputs/wan21_lite_recon.mp4

Tool | What it does
Load H3 LightVAE | The ComfyUI node that loads Lite H3 parts and reuses ComfyUI's native H3 VAE
base_vae | The input where you connect the original H3 video VAE
install.py | Installs the node into your ComfyUI folder
infer.py | Reconstructs a video with chosen encoder and decoder files
lightvae-lite-h3-decoder-int8-convrot.safetensors | The optional quantized H3 Lite decoder for ComfyUI

Example: Run infer.py with the original Wan2.1 encoder and the Lite decoder on demo.mp4, at 81 frames, 480 high and 832 wide. It writes the rebuilt clip to outputs/wan21_lite_recon.mp4 so you can compare it with the source.

For newcomers and experts: A video autoencoder squeezes video into a compact code and expands it back, and it is a big part of video model memory use. LightVAE swaps in smaller versions of those parts. A first small try is the Wan2.1 reconstruction command on a short clip.

For experts, Pro keeps the original decoder depth and adds temporal low-rank compression, while Lite adds block pruning on top. The H3 Lite encoder and decoder were pruned independently. The node reuses ComfyUI's native H3 VAE, so it needs no extra package or custom Triton kernels. The cost is that checkpoints must match their backbone.

Pick the backbone: Wan or H3
Choose Pro or Lite parts
Pair them with the original encoder or decoder
Run in ComfyUI or with infer.py
Compare the output with the source

Good to know: Matching parts to the right backbone matters more than anything else here.

• Matching: keep each checkpoint paired with its own backbone.
• Wan2.2 choice: the 14B models use the Wan2.1 VAE, and TI2V-5B uses the Wan2.2 VAE.
• Node scope: the current ComfyUI node supports H3 only, and the audio VAE stays unchanged.
• INT8 limit: that file is ComfyUI-only and needs a CUDA 13.0 or newer PyTorch build for native acceleration.
• Workflows: they are base-model workflows, not 4-step or 8-step turbo-LoRA workflows.
• License: apache-2.0.
• Cost to run: none named, no API key, account or paid service.
• Data it reaches: the video files you reconstruct, and the files downloaded from Hugging Face.
• Not for: using the INT8 file in the standalone Python scripts.

On Hugging Face, 13 November 2026

• Task: other
• Library: wan2.2
• Downloads in the last 30 days: 819
• Likes: 40
• License: apache-2.0
• Tags: wan2.2, video-vae, video-generation, distillation, image-to-video, text-to-video, comfyui, wan2.1, minimax-h3, other

Links

• Model: https://huggingface.co/lightx2v/LightVAE
• Files: https://huggingface.co/lightx2v/LightVAE/tree/main

Get the model

Download its files with Hugging Face's command line:

pip install -U huggingface_hub
hf download lightx2v/LightVAE

Then follow the usage in its model card. Nothing in this kit runs by itself.