VAEDecodeHunyuan3D

This is the payoff node of a Hunyuan3D workflow. Everything before it - the empty latent, the conditioning, the sampler - produces a latent that means nothing to your eyes. VAEDecodeHunyuan3D decodes that latent into an actual voxel volume, and from there you get a mesh or a model file you can render, save, or drop into a game engine. It's the "3D" in the pipeline finally becoming 3D.

How it works

You feed it the sampled samples (LATENT) and the vae - the Hunyuan3D VAE that came with your checkpoint - and it decodes to a VOXEL output: a three-dimensional occupancy grid of the object. Two settings govern the decode:

• num_chunks (default 8000) - how the decode is chunked for memory management. The VAE decodes the latent in pieces to keep peak VRAM bounded. If you're OOMing on decode, lowering this isn't the fix (that usually makes it worse); you tune it to match your card. If you have plenty of VRAM, you can raise it for speed.
• octree_resolution (default 256, range 16–512) - the resolution of the voxel grid the object is reconstructed into. This is the quality knob: 256 is the standard sweet spot. Higher means a finer grid, more memory, more time; lower gives you a blockier result. 512 is where you go when you want detail and have the hardware to pay for it.

Where it sits and what comes next

The workflow shape is: EmptyLatentHunyuan3Dv2 → conditioning from a reference image or multiview → sampler → this node → VOXEL. Downstream, the voxel grid typically goes through the core helper that converts it to a mesh (voxel_to_mesh, which thresholds and extracts a surface - the threshold there decides what counts as "solid"), then on to a save node for GLB/OBJ or a renderer.

The part people underestimate

That num_chunks setting is not cosmetic. 3D VAE decodes are memory-hungry in a way image decodes aren't - the grid is a cube, and resolution scales cubically, not quadratically. At 256 you're working with 16.7 million voxel cells; at 512 that's 134 million. If you jump octree_resolution to 512 "for quality" and the machine dies, that's why. The sane path is: keep 256, tune num_chunks for your card, and only push resolution when the object genuinely needs it.

Model family note

Hunyuan3D is Tencent's open text/image-to-3D line, and it's been in ComfyUI core since March 2025, with the 2.x line and 2.1 support following. The VAE you load must match the Hunyuan3D version - the decode settings are shaped around its latent space, and a mismatched VAE produces garbage voxels rather than an error. Ships with ComfyUI; nothing to install, just the model files in your checkpoints/vae folders.