H3 X2 Prepare INT8 VAE

What it is, and why you'd bother

This node does one job, once. It reads the original MiniMax-H3-X2-Detail-v1 VAE, converts the heavy part of its decoder to INT8, writes the result into models/vae/h3_x2_stream/, and hands you a VAE object for the X2 decode branch. Run it again and it reuses the file it already made.

Why it's worth a node: the X2 Detail VAE is what doubles your output size - sample at 544 × 960, decode to 1088 × 1920 - and that decode is a real slice of wall clock, not a rounding error. On the author's RTX 4070 12 GB an identical FL2VA run went from ~86.7 s with the X2 VAE in FP16 to 59.7 s with the INT8 decoder. That figure includes the sibling stream-save node's async encoding too, so don't credit it all to quantization - roughly 30% off the same prompt, seed and settings.

How the conversion works

It's narrower than "quantize" implies. Exactly 144 decoder Linear weights - the transformer-block linears - get per-channel INT8 with ConvRot at group size 256. Everything else rides through untouched: encoder, norms, biases, and the final FP16 X2 output projection at [12288, 2048].

ConvRot deserves a sentence of context. It's a rotation trick that knocks down weight outliers so INT8 stays accurate, and ComfyUI adopted it natively in v0.27.0, trumpeting "more than 2x faster than fp16 and gguf on most (Nvidia 20, 30, 40, 50 series) GPUs" and better quality than fp8 (Flux 2 ecosystem § Quantization). It's why 30-series cards, with no fp8 path, stopped being second-class. Kijai's caveat at the time - INT8 plus LoRA offloading was still rough - doesn't bite this VAE: your character LoRA isn't in the X2 decoder.

The quality claim is the author's own: mean PSNR 57.75 / 57.83 dB against the FP16 reference on seven identical-latent raw frames per case - "visually equivalent, not bit-identical".

Inputs and outputs

• source_vae - a dropdown of everything in models/vae. Pick the original MiniMax-H3-X2-Detail-v1.safetensors: the converter rejects already-quantized inputs and only accepts source weights matching the published SHA-256 of the X2 Detail v1 release.
• output_name - defaults to MiniMax-H3-X2-Detail-v1-decoder-int8-convrot.safetensors. Filename only - no directories, no backslashes, no drive letters, must end in .safetensors. Break those rules and you get an error instead of a file in an unexpected place.
• vae (output) - into the X2 decode node's vae input, never the conditioning branch. The decode node checks it's the X2 video VAE and will tell you off otherwise.
• conversion_report (output) - a JSON string: status, output path, byte size, elapsed seconds, source and output hashes, quantized-Linear count. It's an output node, so this also shows in a text widget with no wiring - handy for confirming "reused" versus "converted".

Install and the one-time prep

Install the pack, then restart:

cd ComfyUI/custom_nodes
git clone https://github.com/sepiablue-ai/ComfyUI-H3-X2-Stream.git

# use ComfyUI's own Python - portable: .\python_embeded\python.exe, venv: python
.\python_embeded\python.exe -m pip install -r .\ComfyUI\custom_nodes\ComfyUI-H3-X2-Stream\requirements.txt

Requirements are av>=17.0.0 and safetensors>=0.7.0. comfy-kitchen supplies the INT8 ConvRot layout and ships with ComfyUI 0.37.0+ - don't install it yourself. The pack isn't in the Manager registry, so use Install via Git URL there or the clone above.

Then grab the model and budget disk: speach1sdef178/MiniMax-H3-X2-Detail-VAE on HuggingFace into models/vae/, about 5.25 GB, plus another 2.83 GB for the converted file. Read its terms - they're separate from the code licence, and H3's own community licence excludes the EU, UK, Korea and the US.

To run the conversion alone, queue examples/00_prepare_int8.json - no sampling needed. Advanced users can call quantization.py SOURCE OUTPUT --device cuda:0 with ComfyUI's Python, but the node is the normal path.

Where it goes wrong

"Source SHA-256 does not match." You selected the wrong file. Only the original X2 Detail v1 release is accepted, deliberately.

"Existing target was not made by this converter." A file is already sitting at that name from something else, including the author's earlier private experiment. Pick a different output_name; the converter never overwrites.

A leftover .lock or .h3-x2-* temp file. Normal errors and cancellations clean up after themselves; a process crash doesn't. Confirm nothing is converting, delete the stale file, retry.

Missing CUDA / INT8 kernel errors. There's no CPU fallback: you need a CUDA GPU, CUDA-enabled PyTorch, and a ComfyUI new enough to ship comfy-kitchen. The converter unloads models and clears cache first, so don't queue it behind a running generation.

Where it lands. The file goes to this ComfyUI's models/vae/h3_x2_stream/, full stop - even if the source VAE came from an extra_model_paths.yaml directory. Two installs sharing a model folder means converting twice. The original is never modified.