# 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/3d-generation/hunyuan3d.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.