Hunyuan 3D 2.1 VAE Config

This node looks like a panic attack and does almost nothing on its own. All it does is collect seventeen architecture parameters and hand them to you as a single vae_config value. The real work happens in the node it feeds - Hy3D21VAELoader - which uses that config to construct Tencent's ShapeVAE (the decoder that turns the DiT's latents into a mesh-defining octree).

Here's the thing: the defaults are exactly the right values for the shipped hunyuan3d-vae-v2-1.ckpt. Not approximately - the pack's own batch mesh generator hardcodes this exact same config dictionary internally. So for everyone running the standard checkpoint, this node is a no-op that produces what the loader would use anyway.

The inputs and output

Every input is a pre-wired default. The ones with actual personality:

• num_latents (4096) - how many latent slots the VAE works with; larger = more representational room.
• width (1024) and heads (16) - transformer width and attention heads inside the encoder/decoder.
• num_encoder_layers (8) / num_decoder_layers (16) - the encoder is thinner than the decoder, which makes sense: encoding image features is easier than reconstructing a 3D structure from them.
• scale_factor (1.00395061587524) - that oddly precise default is the exact latent scaling constant the released checkpoint was trained with. Leave it be.
• pc_size (81920) - the point-cloud size the geometry decoder targets.
• The rest (include_pi, qkv_bias, qk_norm, geo_decoder_*, point_feats, pc_sharpedge_size) are architecture switches you'd only touch if you were porting a different checkpoint or experimenting with the ShapeVAE structure itself.

Output: one vae_config (type HY3D21VAECONFIG), which wires into the optional vae_config input on Hy3D21VAELoader. If you don't connect it, the loader silently falls back to that same hardcoded default dict - so nothing breaks if you ignore this node entirely.

Why it exists, then

Two reasons, and neither is for beginners. First, it exposes the architecture so a workflow can be explicit about what it's loading - you can read the config off the canvas instead of trusting the loader's hidden defaults. Second, and more practically: if you ever load a custom/finetuned ShapeVAE that doesn't match the stock architecture, this is the escape hatch to tell the loader what you actually have. That's a deep-dive scenario; the sort of thing you'd do after a month of wrestling with the pack, not on day one.

Install & usage

It comes with the ComfyUI-Hunyuan3d-2-1 pack - install that (see the mesh generator page for the full requirements + checkpoint + C++ extension drill). There's no model loading here, so none of the pack's heavy dependencies matter for this node specifically. Drop it in front of a Hy3D21VAELoader, leave the defaults, and you have a slightly more legible graph. Or skip it. Both are correct.