# Hunyuan3D 2.1

Hunyuan3D 2.1 by Tencent is a two-stage 3D generation model: it first predicts geometry (shape), then synthesizes PBR textures. It accepts both text prompts and reference images as input and outputs production-ready meshes in GLB, OBJ, or PLY format. With over 3 million downloads on HuggingFace, it is one of the most widely adopted open-source 3D generation models.

{% hint style="success" %}
All examples run on GPU servers rented through the [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## Key Features

* **Text-to-3D and image-to-3D** — both input modes in a single model
* **Two-stage pipeline** — shape generation followed by PBR texture synthesis
* **High-fidelity output** — detailed geometry with albedo, normal, and roughness maps
* **Multiple export formats** — GLB, OBJ, PLY
* **Gradio web UI** — browser-based interaction, no coding required
* **16–24 GB VRAM** — runs on RTX 3090 and RTX 4090
* **3M+ downloads** on HuggingFace — active community and continuous updates

## Requirements

| Component | Minimum        | Recommended    |
| --------- | -------------- | -------------- |
| GPU       | RTX 3090 24 GB | RTX 4090 24 GB |
| VRAM      | 16 GB          | 24 GB          |
| RAM       | 16 GB          | 32 GB          |
| Disk      | 50 GB          | 100 GB         |
| CUDA      | 11.8           | 12.1+          |
| Python    | 3.10           | 3.11           |

**Clore.ai pricing:** RTX 4090 ≈ $0.5–2/day · RTX 3090 ≈ $0.3–1/day

## Quick Start

### 1. Clone and Install

```bash
git clone https://github.com/Tencent/Hunyuan3D-2.git
cd Hunyuan3D-2

# Create environment
conda create -n hunyuan3d python=3.10 -y
conda activate hunyuan3d

# Install PyTorch
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# Install dependencies
pip install -r requirements.txt

# Download model weights (auto-downloaded on first run, ~15 GB total)
python -c "from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline; Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')"
```

### 2. Launch the Gradio Web UI

```bash
python gradio_app.py --port 7860 --share
```

The UI provides:

* Text input field for text-to-3D generation
* Image upload for image-to-3D generation
* Sliders for inference steps, guidance scale, and seed
* 3D model preview with orbit controls
* Download buttons for GLB/OBJ/PLY

### 3. Generate via Python API

```python
from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline
from hy3dgen.texgen import Hunyuan3DPaintPipeline

# Stage 1: Shape generation
shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="shapegen",
)
shape_pipeline.to("cuda")

# Generate mesh from text
mesh = shape_pipeline(
    prompt="a detailed medieval sword with ornate handle",
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

mesh.export("sword_shape.glb")
```

### 4. Add Textures (Stage 2)

```python
# Stage 2: Texture synthesis
texture_pipeline = Hunyuan3DPaintPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="texgen",
)
texture_pipeline.to("cuda")

textured_mesh = texture_pipeline(
    mesh=mesh,
    prompt="a detailed medieval sword with ornate handle",
    num_inference_steps=20,
    seed=42,
)[0]

textured_mesh.export("sword_textured.glb")
```

## Usage Examples

### Image-to-3D Generation

```python
from PIL import Image

# Load reference image
image = Image.open("reference_chair.png")

# Generate shape from image
mesh = shape_pipeline(
    image=image,
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

# Apply texture
textured = texture_pipeline(
    mesh=mesh,
    image=image,
    num_inference_steps=20,
    seed=42,
)[0]

textured.export("chair.glb")
```

### Batch Processing

```python
from pathlib import Path

prompts = [
    "a red sports car, low-poly game asset",
    "a wooden treasure chest, PBR material",
    "a sci-fi helmet with visor, hard surface",
]

output_dir = Path("/workspace/3d-output")
output_dir.mkdir(exist_ok=True)

for i, prompt in enumerate(prompts):
    mesh = shape_pipeline(prompt=prompt, num_inference_steps=30, seed=42)[0]
    textured = texture_pipeline(mesh=mesh, prompt=prompt, num_inference_steps=20, seed=42)[0]
    textured.export(str(output_dir / f"asset_{i:03d}.glb"))
    print(f"Generated: asset_{i:03d}.glb — {prompt[:40]}")
```

### Export to Multiple Formats

```python
# GLB (recommended — includes textures, universal format)
textured_mesh.export("model.glb")

# OBJ (with MTL material file)
textured_mesh.export("model.obj")

# PLY (vertex colors, point cloud compatible)
textured_mesh.export("model.ply")
```

## Performance Reference

| GPU      | Shape (30 steps) | Texture (20 steps) | Total    |
| -------- | ---------------- | ------------------ | -------- |
| RTX 4090 | \~20 sec         | \~15 sec           | \~35 sec |
| RTX 3090 | \~30 sec         | \~25 sec           | \~55 sec |
| A100 40G | \~18 sec         | \~12 sec           | \~30 sec |

## Tips

* **Remove image backgrounds** before image-to-3D — use `rembg` for clean segmentation
* **Text prompts benefit from specificity** — "a low-poly medieval sword with leather-wrapped handle" produces better results than "sword"
* **Reduce `num_inference_steps`** to 15–20 for faster previews during iteration
* **Increase `guidance_scale`** (8–12) for stronger adherence to the prompt at the cost of diversity
* **GLB is the best export format** — it bundles geometry, textures, and materials in a single file
* **Use `--share`** when launching Gradio on Clore.ai for remote browser access
* **Model weights are \~15 GB** — ensure sufficient disk space before first run
* **For game assets**, generate at high quality then decimate in Blender for LOD levels

## Troubleshooting

| Problem                        | Solution                                                                        |
| ------------------------------ | ------------------------------------------------------------------------------- |
| `CUDA out of memory`           | Use RTX 3090+ (24 GB). Reduce batch size or inference steps                     |
| Model download stalls          | Check disk space. Use `huggingface-cli download tencent/Hunyuan3D-2` manually   |
| Gradio UI not reachable        | Pass `--share` flag, or forward port 7860 from Clore.ai dashboard               |
| Poor geometry quality          | Increase `num_inference_steps` to 40+, try different seeds                      |
| Texture artifacts              | Ensure shape mesh is clean before texture stage                                 |
| Import errors on fresh install | Run `pip install -r requirements.txt` again — some deps compile from source     |
| Slow generation on first run   | Expected — model compilation and weight loading is cached after first inference |

## Resources

* [Hunyuan3D-2 GitHub](https://github.com/Tencent/Hunyuan3D-2)
* [HuggingFace Model](https://huggingface.co/tencent/Hunyuan3D-2)
* [CLORE.AI Marketplace](https://clore.ai/marketplace)