Hunyuan3D 2.1

Generate 3D meshes from text or images with Tencent Hunyuan3D 2.1 on Clore.ai

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.

All examples run on GPU servers rented through the CLORE.AI Marketplace.

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

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

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

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)

# 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

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

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

# 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

• HuggingFace Model

• CLORE.AI Marketplace