hunyuan3D-2.1

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.

<table> <tr><td><img src="https://huggingface.co/ChrisColeTech/hunyuan3D-2.1/resolve/main/samples/src-robot.png" width="330" alt="source photograph of a retro robot toy"></td><td><img src="https://huggingface.co/ChrisColeTech/hunyuan3D-2.1/resolve/main/samples/mesh-robot.png" width="330" alt="generated mesh, front three-quarter view"></td></tr> <tr><td>_{**source** — `a cute chunky retro robot toy standing upright, rounded metal body, simple friendly face, studio product photograph on a plain white background`}</td><td>_{**mesh** — 9.7 MB `.glb`, generated in 69 s, seed 42}</td></tr> <tr><td><img src="https://huggingface.co/ChrisColeTech/hunyuan3D-2.1/resolve/main/samples/src-teapot.png" width="330" alt="source photograph of a porcelain teapot"></td><td><img src="https://huggingface.co/ChrisColeTech/hunyuan3D-2.1/resolve/main/samples/mesh-teapot.png" width="330" alt="generated mesh, front three-quarter view"></td></tr> <tr><td>_{**source** — `an ornate ceramic teapot with a curved spout and handle, glazed blue and white porcelain, studio product photograph`}</td><td>_{**mesh** — 14.6 MB `.glb`, generated in 39 s, seed 42}</td></tr> </table>

Textured (img2mesh_textured)

The same robot through the full chain — 2.1 shape, then the paint stage — instead of shape alone.

<table> <tr><td><img src="https://huggingface.co/ChrisColeTech/hunyuan3D-2.1/resolve/main/samples/mesh-robot.png" width="330" alt="untextured shape output"></td><td><img src="https://huggingface.co/ChrisColeTech/hunyuan3D-2.1/resolve/main/samples/mesh-robot-textured.png" width="330" alt="same mesh after the paint stage"></td></tr> <tr><td>_{**`img2mesh`** — 9.7 MB, **69 s**}</td><td>_{**`img2mesh_textured`** — 19.3 MB with a baked base-colour texture, **+14 min** for the paint stage}</td></tr> </table>

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

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 mv checkpoints — this model takes one image.
• img2mesh output is untextured; texturing is a separate paint stage. img2mesh_textured chains 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_resolution is 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

---

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.