Hunyuan3D

Image-to-3D. Give it one photograph and it returns a triangle mesh.

Unlike every other family in mold, Hunyuan3D has no text encoder at all. The source image is the only conditioning, so a prompt is recorded as provenance and never read, and a request without an image is refused rather than answered from an empty prompt.

No prompt is needed anywhere. The model's generation profile says so, and every surface reads it, so mold run hunyuan3d-mini-turbo --image chair.png is a complete request from the CLI, the API, the TUI, Discord and the apps alike.

Available in the web SPA, the desktop app, and the iPhone app, not only the CLI. Picking this model in Create reshapes the form from its generation profile: the raster controls disappear and a Mesh control group (Octree, Iso threshold, Target faces) takes their place. See 3D Meshes → From the apps for the walkthrough.

• Developer: Tencent Hunyuan
• License: separate Tencent Hunyuan 3D 2.0 and 2.1 terms — see Licence below, because it has real restrictions
• HuggingFace: tencent/Hunyuan3D-2, tencent/Hunyuan3D-2mini

Variants

Model	Steps	Size	VRAM	Notes
hunyuan3d-mini-turbo:fp16	5	3.6 GiB	~5 GB	0.6B, step-distilled. The default.
hunyuan3d-turbo:fp16	5	4.6 GiB	~6 GB	1.1B, step-distilled
hunyuan3d:fp16	30	4.6 GiB	~6 GB	1.1B, undistilled
hunyuan3d-2.1:fp16	30	6.9 GiB	~8 GB shape VAE round-trip	3.3B MoE shape transformer; separate 2.1 licence
hunyuan3d-2mv:fp16	30	4.6 GiB	~6 GB	1–4 named views, undistilled
hunyuan3d-2mv-turbo:fp16	5	4.6 GiB	~6 GB	1–4 named views, step-distilled

Named multiview shape

The 2mv checkpoints accept any non-empty subset of front, left, back, and right views. Slots are semantic: omitting left does not renumber back.

mold pull hunyuan3d-2mv-turbo --accept-license tencent-hunyuan3d-2.0
mold run hunyuan3d-2mv-turbo \
  --front chair-front.png --left chair-left.png --back chair-back.png \
  -o chair.glb

Create shows the same four named wells on web, desktop, and phones. The MCP generate_mesh tool accepts the corresponding front, left, back, and right base64 fields when its model is a 2mv tier.

Each is ONE self-contained file carrying the shape transformer, the shape VAE and an image encoder (DINOv2-large for 2.1, giant for 2.0), which is why a "0.6B" model is still 3.6 GiB — the vision tower is 1.1B parameters on its own.

No quantized variants exist upstream. mold can derive them locally from an installed fp16 checkpoint with mold quantize; the source file is preserved, the derived model is registered atomically, and every app discovers it through the normal installed-model list.

Shape checkpoint	CUDA-qualified derived tiers
2.1 sparse MoE	fp8, q8, q4
2.0 full, undistilled	fp8, q8
2.0 full Turbo	fp8, q8, q6, q5, q4, q3
2.0 mini Turbo	q8, q4
2mv Turbo	q8, q6, q5, q4, q3

q2 is deliberately refused because qualification produced invalid geometry. FP8 uses group-of-32 E4M3 scaling on large expert/MLP matrices and leaves attention, modulation, input/output, VAE and vision weights in their source dtype. Quantized execution is CUDA-only; Metal reports the unsupported tier before loading weights.

mold quantize hunyuan3d-2.1:fp16 --tier fp8
mold quantize hunyuan3d-2mv-turbo:fp16 --tier q4

Measured on Apple Silicon

hunyuan3d-mini-turbo:fp16 on an M4 Max (48 GB), fp16, the default decode chunk, one seed, a background-removed armchair. ComfyUI is the same checkpoint and seed on the same machine through PyTorch MPS.

Octree	Wall	Peak RSS	Mesh	ComfyUI wall
192	77 s	7.2 GB	145k vertices, 317k tris	44 s
256	144 s	7.2 GB	264k vertices, 590k tris	79 s
320	256 s	7.2 GB	417k vertices, 930k tris	136 s

The geometry matches ComfyUI's to a normalised Chamfer distance of 0.011 on every rung, with bounding-box extents within 5 % and triangle counts within 19 %; two mold seeds differ from each other by 0.0025 on the same scale. mold is slower than PyTorch here: the volume decode (over 90 % of the wall time) runs through candle's chunked math attention on Metal rather than a fused kernel, and the tile size has already been swept — 512-row tiles are the fastest. CUDA has not been measured yet.

Hunyuan3D 2.1 shape

mold pull hunyuan3d-2.1 --accept-license tencent-hunyuan3d-2.1
mold run hunyuan3d-2.1 --image chair.png -o chair.glb

The 2.1 checkpoint uses a different transformer with sparse experts and 4,096 shape latents. Accepting the 2.0 terms does not accept the 2.1 terms. The default remains mini-turbo.

The web and desktop 3-D Studio can also rebuild a supplied GLB or OBJ through the 2.1 shape VAE. Choose Rebuild a mesh, declare whether the input is Y-up or Z-up and its metres-per-unit scale, and submit it as a durable workflow. mold normalizes the source, samples its surface deterministically from the request seed, encodes all 81,920 points into 4,096 latents, decodes a fresh surface, and publishes the result as a new Library GLB. The source mesh and stage checkpoint survive app or server restarts.

The installed fp16 Shape VAE is tensor-qualified against Tencent's 2.1 implementation, a full GLB round trip is geometry-qualified on CUDA, and image conditioning through the 2.1 sparse top-2 MoE transformer is qualified end to end. Its fp8, q8, and q4 tiers produced Khronos-clean GLBs in comparison with fp16.

Getting good results

Prompt quality is irrelevant here. Source image quality is everything.

• One object, centred, filling most of the frame. The model reconstructs what it can see; a subject occupying a tenth of the frame reconstructs at a tenth of the detail.
• A plain or removed background. There is no segmentation stage, so a busy background is read as geometry. An image with an alpha channel is letterboxed on its cutout, which is the best input you can give it.
• A three-quarter view. A straight-on photograph gives the model no depth cue for the sides.

Usage

mold pull hunyuan3d-mini-turbo --accept-license tencent-hunyuan3d-2.0
mold run hunyuan3d-mini-turbo --image chair.png -o chair.glb

Higher detail, undistilled tier:

mold run hunyuan3d --image chair.png --octree 320 -o chair.glb

Pipe it straight into a viewer:

mold run hunyuan3d-mini-turbo --image chair.png --output - | some-gltf-viewer

Controls

Flag	Default	What it does
--octree	256	Query-grid resolution. The detail knob; cost is cubic.
--mesh-threshold	0.6	Iso-level. Lower recovers thin features and adds noise.
--target-faces	none	Decimate to approximately this triangle count.

The threshold is a level on the same [0, 1] occupancy scale ComfyUI's VoxelToMesh node thresholds, so a value that works in ComfyUI works here unchanged. (Internally the VAE's raw logits are mapped through (x + 1) / 2, clamped, before the surface is extracted — 0.6 sits at raw logit 0.2.)

--octree accepts 128, 192, 256, 320 or 384. It is an allowlist rather than a range because the shape VAE evaluates its occupancy field on (n + 1)³ points — 256 is about 17 million — so an arbitrary number between two rungs buys nothing and can cost you an out-of-memory failure minutes into a render.

Output

The stored artifact is always binary glTF (.glb): one self-contained file with geometry, normals and materials embedded, so a mesh is one library print exactly like an image or a clip. It gets a rendered poster tile in the gallery, and it lists, downloads, trashes, restores and reuses its settings like anything else.

A 3-D model has exactly one deliverable container, so a request naming a raster format is pinned to glb rather than refused. -o is the exception: a filename ending in .png or .mp4 names a file this render will not write, so it is refused before any weight is read.

Export as OBJ, ZIP, STL or PLY

Everything except GLB is an export — a transcode of a mesh that already exists, never a stored format — because each of them loses something the glTF carries.

mold library export chair.glb --format stl
mold library export chair.glb --format obj -o ~/chair.obj
mold library export chair.glb --format zip -o ~/chair.zip

Format	Carries	Reach for it when
glb	Geometry, normals, UVs, materials, embedded texture	Anything. This is the stored file.
obj	Positions, normals, UVs. No materials.	Blender, MeshLab, most DCC importers.
zip	OBJ, MTL, base color, metallic-roughness and normal maps.	Moving a painted asset between tools.
stl	Triangles and one normal each. No UVs, no colour.	3-D printing and CAD.
ply	Positions and per-vertex normals, vertices shared.	Point-and-mesh tooling, research code.

The gallery file is never renamed or replaced. The same conversions are on POST /api/gallery/export/:filename and the export_mesh MCP tool, and a host advertises what it can convert on /api/capabilities.mesh.export_formats. Painted prints also list their maps in GalleryImage.assets; the web, desktop, and mobile viewers offer each as an exact independent download. --size-mm, --up-axis and --origin make an STL or PLY print-ready for a slicer or DCC tool by default; see Print-ready exports.

Licence

Tencent's community licence for these weights has two clauses worth reading before you build on them:

THIS LICENSE AGREEMENT DOES NOT APPLY IN THE EUROPEAN UNION, UNITED KINGDOM AND SOUTH KOREA

and a separate written licence from Tencent is required once your products exceed 1 million monthly active users.

Outputs are unencumbered — "Tencent claims no rights in Outputs You generate" — so the meshes themselves are yours.

Because of this, mold refuses to download the weights until you have recorded an acceptance:

mold licenses                      # read the terms
mold licenses accept tencent-hunyuan3d-2.0   # agree without downloading
mold pull hunyuan3d --accept-license tencent-hunyuan3d-2.0

This is the same gate the InsightFace face models use. It exists so a server-side auto-pull can never quietly acquire restricted weights on your behalf.

PBR painting

Shipping builds remove opaque image backgrounds with a pinned pure-Rust U²-Net pre-stage before Hunyuan3D reads the image. --matting auto preserves a useful existing alpha channel and processes an opaque input; on recomputes the mask; off keeps the pixels unchanged. The same choices appear in web, desktop, mobile, TUI, Discord, and MCP clients when the host advertises them. For a durable gallery render, mold retains the exact processed cutouts as encrypted, authenticated downloads alongside the original inputs; they survive restart and follow the print's permanent-deletion lifecycle, but cannot be selected for request reuse because doing so would apply matting twice.

CUDA builds advertise Remove lighting and highlights when the pinned Hunyuan3D Delight pipeline is linked. Enable it with --delight or the Mesh switch in web, desktop, and mobile. Mold runs the fixed Tencent recipe after matting and before shape or paint, then retains the delighted PNG as its own durable stage artifact. The 512px, 50-step Euler ancestral recipe uses seed 42 and has no adjustable prompt or strength.

CUDA builds with mesh-texture can run Hunyuan3D Paint after shape generation and embed base color, metallic/roughness and normal textures in the stored GLB. Use --texture [--texture-resolution 1024|2048|4096] on the CLI, or enable PBR materials in the desktop Create inspector. The 3-D Studio also runs durable text-to-3D and supplied-mesh retexturing workflows, with optional matting and delight preprocessing checkpointed before shape or paint. The Library preserves the original encoded base-color, metallic-roughness, and normal PNGs inside the GLB, indexes them as generation assets, and can download them separately or package them with OBJ + MTL through --format zip.

Accepting the licence from the apps

The terms are not CLI-only. Selecting a Hunyuan3D model on web, desktop or mobile raises the shared licence dialog before anything downloads, as does installing it from the Models page. Acceptance is recorded per Mold data root, so it is stored on the host that will fetch the weights — on desktop, pick that machine in Settings → Model licenses, and on mobile it is whichever host you have selected.

The 2.1 shape model and texturing weights (hunyuan3d-paint) share a separate Tencent 2.1 agreement and must be accepted on their own before PBR painting.