Hunyuan3D-2.1 — 3.3B MoE image-to-3D
The 2.1-generation Hunyuan3D shape model: a 3.3B mixture-of-experts DiT (21 blocks, 6 MoE layers × 8 experts) with a 4096-latent ShapeVAE and DINOv2-Large conditioning. ≈40–70 s per mesh on an RTX 5090.
What this repo is: the Hunyuan3D-2.1 DiT and ShapeVAE — weights only, not a retrain. The samples below were generated with this build.
Samples
Single image in, mesh out. Source images were rendered with Z-Image Turbo; the
meshes are Blender Workbench clay renders of the raw .glb output.
Textured (img2mesh_textured)
The same robot through the full chain — 2.1 shape, then the paint stage — instead of shape alone.
Turntable
Four views, 90° apart — the back is inferred, not copied.
The recessed chest display, the dial below it and the boot flare all survive, and the moulded facial detail reads cleanly. Surfaces are smooth and closed rather than noisy — the MoE DiT's main visible advantage over the smaller models in this family.
Recommended settings
| Parameter | Production value | Meaning |
|---|---|---|
steps | 50 | Denoising steps |
guidance | 5.0 | Guidance scale |
octree_resolution | 384 | Marching-cubes grid resolution |
seed | any | Deterministic per seed |
| output | .glb | Watertight triangle mesh, no texture |
Supported modes: img2mesh, img2mesh_textured (texturing runs as a separate paint stage)
Notes and gotchas
- Single-view only. Multi-view conditioning stays on the 2.0
mvcheckpoints — this model takes one image. img2meshoutput is untextured; texturing is a separate paint stage.img2mesh_texturedchains a paint model after this one and produces a correctly textured mesh, but costs ≈14 minutes on top of the 69 s shape stage — most of it a pure-Python UV hole-filling loop rather than GPU work. Plan the textured path as a batch job.octree_resolutionis the memory/detail dial. 384 is the production value; raising it sharpens fine relief but grows the marching-cubes grid cubically.- Directory naming matters. These weights ship under the upstream release
name (
hunyuan3D-2.1) rather than a package-style name — a loader that hardcodes the latter will find an empty directory and report the checkpoints as missing. - Give the GPU to one model at a time. At 3.3B this wants the card to itself; sharing a GPU with another model-serving process produces failures that look like crashes rather than clean out-of-memory errors.
- Generated meshes come out facing the source image's front, so a fixed camera works across a batch.
Files
| Path | Size | Role |
|---|---|---|
split/hunyuan3d-dit-v2-1/model.fp16.ckpt | 6.9 GB | 3.3B MoE shape DiT |
split/hunyuan3d-vae-v2-1/model.fp16.ckpt | 626 MB | ShapeVAE (4096 latents) |
Provenance
- Upstream base model:
tencent/Hunyuan3D-2.1 - This build: redistributed as a split component tree. Weights are not retrained here.
- License: Tencent Hunyuan3D community license — refer to upstream for redistribution and commercial-use terms.