Hy3DVAELoader

Hy3DVAELoader is the little sibling of Hy3DModelLoader. Where the model loader bundles a VAE for you, this node loads a specific Hunyuan3D VAE checkpoint on its own - the one you pick from ComfyUI/models/vae/ - and hands back a HY3DVAE for Hy3DVAEDecode.

Honestly, in the default 2.0 flow you probably won't need it. Hy3DModelLoader already hands you a vae output for free. This node exists for the case where you want a different VAE than the one baked into the shape checkpoint - most notably the turbo VAE that ships with Hunyuan3D 2.1's fast path, which decodes shape latents much quicker. If you're running the 2.1 workflow that generates latents at turbo speed, you'll be reaching for this.

How it works

One input, one output. model_name is a dropdown populated from ComfyUI/models/vae/; the vae output plugs into Hy3DVAEDecode.

The interesting bit is under the hood: it loads the state dict into a ShapeVAE and auto-detects whether you've given it the turbo VAE by checking for a specific layer (geo_decoder.ln_post.weight). If that layer is missing, it configures the VAE in turbo mode - different MLP expansion ratio, different downsampling - rather than making you flip a switch. Nice touch, and it means "which model do I use" is answered by just dropping the right file in the folder.

Install and setup

Same pack install as everything else in the wrapper - ComfyUI Manager or:

cd ComfyUI/custom_nodes
git clone https://github.com/kijai/ComfyUI-Hunyuan3DWrapper
pip install -r ComfyUI-Hunyuan3DWrapper/requirements.txt

Then put the VAE file in ComfyUI/models/vae/ and it appears in the dropdown. Note the pack autodownloads the diffusers-style models (paint, delight) on its own, but a VAE for this node is a raw checkpoint you place yourself - the turbo VAE ships with Hunyuan3D 2.1's release, so grab it from the Tencent repo (mind the territory-limited license) and drop it in the folder.

Common issues

• Empty dropdown - you haven't placed a VAE in ComfyUI/models/vae/. A standard load_torch_file + state-dict load means it wants the raw checkpoint, so make sure the file actually made it there.
• Decode looks wrong or crashes - you've likely mixed the turbo and standard VAEs mid-workflow. The loader detects the type automatically, but the pipeline that produced the latents needs to match the VAE you decode with. Keep the pair consistent: standard latents with the standard VAE, turbo with turbo.
• VRAM - the VAE loads into fp16 and gets offloaded after decode, but during decode it sits on the GPU alongside everything else. Hy3DVAEDecode's num_chunks setting is your memory lever when this bites.