Hunyuan3D-2.1-MLX-Serve-8bit

Hunyuan3D 2.1 for MLX Core / mlx-serve (8-bit, combined)

Photo → textured, rigged 3D model — fully on-device on Apple Silicon. This is the complete 3D generation stack for mlx-serve / MLX Core, converted to MLX-native safetensors and quantized to 8-bit (group size 64), packaged as one repo so the app downloads one thing:

Total ≈ 8.1 GB. Dense tensors are fp16; eligible linears are 8-bit affine-quantized.

Use

The MLX Core app's 3D pane downloads this automatically. With a standalone mlx-serve:

hf download ddalcu/Hunyuan3D-2.1-MLX-Serve-8bit --local-dir ~/.mlx-serve/models/ddalcu/Hunyuan3D-2.1-MLX-Serve-8bit
mlx-serve --serve --model-dir ~/.mlx-serve/models

curl http://localhost:8080/v1/3d/generations -H 'Content-Type: application/json' -d '{
  "model": "ddalcu/Hunyuan3D-2.1-MLX-Serve-8bit",
  "image": "<base64 PNG/JPEG>",
  "texture": true,
  "rig": true
}'   # → {"format":"glb","data":"<base64 GLB>"} — a textured, rigged glTF binary

texture and rig are optional (shape-only is fastest); the server resolves the paint/ and unirig/ stages from this repo's subdirectories automatically.

Conversion & parity

Converted with the scripts in the mlx-serve repo (tests/convert_hunyuan3d_weights.py, tests/convert_hunyuan3d_paint_weights.py, tests/convert_unirig_weights.py). The native Zig engines were validated against the PyTorch references with cosine-similarity oracles: shape e2e SDF grid 0.9998, paint full-UNet denoise step 1.0000, UniRig greedy skeleton decode token-exact. Structural transforms (per-head QKV de-interleaves, MoE expert stacking, NCHW→OHWI conv layout) are baked out at convert time.

Licenses

• Shape + paint weights: Tencent Hunyuan3D-2.1 Community License (also paint/LICENSE).
• DINOv2 encoders (conditioner.safetensors, paint/dino.safetensors): Apache-2.0 (Meta AI).
• UniRig skeleton weights: MIT (VAST-AI-Research); see unirig/NOTICE for the code/weights licensing split.