---
license: other
pipeline_tag: image-to-3d
tags:
  - image-to-3d
  - 3d-generation
  - mesh-generation
  - hunyuan3d
  - moe
base_model:
  - tencent/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><sub>**source** — `a cute chunky retro robot toy standing upright, rounded metal body, simple friendly face, studio product photograph on a plain white background`</sub></td><td><sub>**mesh** — 9.7 MB `.glb`, generated in 69 s, seed 42</sub></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><sub>**source** — `an ornate ceramic teapot with a curved spout and handle, glazed blue and white porcelain, studio product photograph`</sub></td><td><sub>**mesh** — 14.6 MB `.glb`, generated in 39 s, seed 42</sub></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><sub>**`img2mesh`** — 9.7 MB, **69 s**</sub></td><td><sub>**`img2mesh_textured`** — 19.3 MB with a baked base-colour texture, **+14 min** for the paint stage</sub></td></tr>
</table>

### Turntable

Four views, 90° apart — the back is inferred, not copied.

![robot turntable](https://huggingface.co/ChrisColeTech/hunyuan3D-2.1/resolve/main/samples/turntable-robot.png)

![teapot turntable](https://huggingface.co/ChrisColeTech/hunyuan3D-2.1/resolve/main/samples/turntable-teapot.png)

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 `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

| 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`](https://huggingface.co/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.