MiniMax-H3 Single-Frame VAE Loader (BFS)

The crisp stills people get out of MiniMax-H3 come from a community-trained single-frame decoder (iamkaikai/MiniMax-H3-Single-Frame-VAE-500K, 500k training images). And that checkpoint is a trap for ComfyUI's stock VAELoader. It's decoder-only and ships in diffusers key naming, and ComfyUI's sd.py detects the MiniMax architecture by the presence of an encoder key (encoder.down.5.block.0.conv1.weight). A decoder-only file doesn't have one, so the loader silently guesses wrong - Stable Diffusion geometry - and you get a grid of blocks instead of a picture. No error, just garbage.

This node solves both sides at once. It loads the decoder-only checkpoint, converts its diffusers naming to ComfyUI's layout, and fills in everything the file is missing - the encoder, quant_conv, latents_mean/std, mask_token - from the official full H3 VAE. Two of those conversions aren't deducible by name and were worked out by measuring correlation against the official VAE: the attention to_qkv is interleaved per head (heads, 3, dim_head) rather than stacked [q;k;v], and ff.w1's halves are swapped because ComfyUI reads gate, x = w1(x).chunk(2). Get either wrong and you get wrong output with zero load errors. The author validated the result against his own diffusers reference path on the same latent at PSNR 72.92 dB - that's fp16 noise, the outputs are effectively identical.

The inputs that matter

• base_vae - the official full H3 VAE (the one with an encoder). It supplies everything the decoder-only file lacks.
• single_frame_decoder - the decoder-only checkpoint (585 tensors, diffusers naming). The node also accepts one you've already converted to ComfyUI naming.
• tiling - keep it on. Above ~768px, whole-image decode of the H3 VAE shows a grid at 32px boundaries (blocking ~2.9x at 1024, ~3.5x at 1536, vs ~1.5x with tiling). Turning it off only pays off on small images, where you buy a little sharpness.
• tile_size - 512, and this is a measured optimum, not a guess: on a 1056x640 image it scores PSNR 26.00 dB with a seam score of 0.91 (indistinguishable), versus 22.17 / 1.49 at 256 (ComfyUI's own default - it multiplies seams) and 21.35 / 2.42 at 1024 (above trained resolution). The card's author trained 475k of the 500k images at ≤512px, so a 512 tile keeps every patch inside the region with training mass.
• dtype - float16 by default; float32 or bfloat16 available if you want to test precision.

Output is a single VAE. Wire it into MiniMaxH3DirectDecode for stills, or into the sampler as the VAE for latent previews.

Installing it

The pack installs like any custom node - ComfyUI Manager (search ComfyUI-BFSNodes) or:

cd ComfyUI/custom_nodes
git clone https://github.com/alisson-anjos/ComfyUI-BFSNodes.git
cd ComfyUI-BFSNodes
pip install -r requirements.txt

Restart ComfyUI. Then drop both checkpoints into ComfyUI/models/vae: the official full H3 VAE and the single-frame decoder file. The node needs both - that's the whole premise.

Common issues

The error "não parece o VAE oficial do MiniMax-H3" (missing detect keys) means your base_vae isn't the full official file - pick the one with the encoder. A shape-divergence error means the decoder file doesn't match the base architecture. And if the decoder file happens to also carry an encoder, the node prints a warning that it overwrote the base's encoder - worth reading in the console, not just dismissing.

The one thing to internalize: this node exists because the checkpoint cannot be loaded any other way. If someone's workflow loads the single-frame file through a plain VAELoader, that's the blocks-grid you're trying to avoid.