Hunyuan3D 2.1

Générez des maillages 3D à partir de texte ou d'images avec Tencent Hunyuan3D 2.1 sur Clore.ai

Hunyuan3D 2.1 de Tencent est un modèle de génération 3D en deux étapes : il prédit d’abord la géométrie (la forme), puis synthétise des textures PBR. Il accepte à la fois des prompts textuels et des images de référence en entrée, et produit des maillages prêts pour la production au format GLB, OBJ ou PLY. Avec plus de 3 millions de téléchargements sur HuggingFace, c’est l’un des modèles de génération 3D open source les plus largement adoptés.

Tous les exemples s’exécutent sur des serveurs GPU loués via la place de marché CLORE.AI.

Caractéristiques clés

• Texte vers 3D et image vers 3D — les deux modes d’entrée dans un seul modèle

• Pipeline en deux étapes — génération de la forme suivie de la synthèse de textures PBR

• Sortie haute fidélité — géométrie détaillée avec cartes d’albédo, de normal et de rugosité

• Plusieurs formats d’export — GLB, OBJ, PLY

• Interface web Gradio — interaction via le navigateur, aucun codage requis

• 16–24 Go de VRAM — fonctionne sur RTX 3090 et RTX 4090

• 3M+ téléchargements sur HuggingFace — communauté active et mises à jour continues

Exigences

Composant	Minimum	Recommandé
GPU	RTX 3090 24 Go	RTX 4090 24 Go
VRAM	16 Go	24 Go
RAM	16 Go	32 Go
Disque	50 Go	100 Go
CUDA	12.8+	12.8+
Python	3.10	3.11

Tarification Clore.ai : RTX 4090 ≈ 0,14–0,42 $/h · RTX 3090 ≈ 0,07–0,21 $/h

Démarrage rapide

1. Cloner et installer

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

# Créer l'environnement
conda create -n hunyuan3d python=3.10 -y
conda activate hunyuan3d

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

# Installer les dépendances
pip install -r requirements.txt

# Télécharger les poids du modèle (téléchargés automatiquement au premier lancement, ~15 Go au total)
python -c "from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline; Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')"

2. Lancer l'interface web Gradio

python gradio_app.py --port 7860 --share

L'interface fournit :

• Champ de saisie de texte pour la génération texte vers 3D

• Téléversement d'image pour la génération image vers 3D

• Curseurs pour les étapes d'inférence, l'échelle de guidage et la graine

• Aperçu du modèle 3D avec commandes d'orbite

• Boutons de téléchargement pour GLB/OBJ/PLY

3. Générer via l'API Python

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

# Étape 1 : génération de la forme
shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="shapegen",
)
shape_pipeline.to("cuda")

# Générer un maillage à partir du texte
mesh = shape_pipeline(
    prompt="une épée médiévale détaillée avec une poignée ornée",
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

mesh.export("sword_shape.glb")

4. Ajouter les textures (étape 2)

# Étape 2 : synthèse des textures
texture_pipeline = Hunyuan3DPaintPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="texgen",
)
texture_pipeline.to("cuda")

textured_mesh = texture_pipeline(
    mesh=mesh,
    prompt="une épée médiévale détaillée avec une poignée ornée",
    num_inference_steps=20,
    seed=42,
)[0]

textured_mesh.export("sword_textured.glb")

Exemples d'utilisation

Génération image vers 3D

from PIL import Image

# Charger l'image de référence
image = Image.open("reference_chair.png")

# Générer la forme à partir de l'image
mesh = shape_pipeline(
    image=image,
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

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

textured.export("chair.glb")

Traitement par lots

from pathlib import Path

prompts = [
    "une voiture de sport rouge, asset de jeu low-poly",
    "un coffre au trésor en bois, matériau PBR",
    "un casque de science-fiction avec visière, surface dure",
]

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"Généré : asset_{i:03d}.glb — {prompt[:40]}")

Exporter dans plusieurs formats

# GLB (recommandé — inclut les textures, format universel)
textured_mesh.export("model.glb")

# OBJ (avec fichier de matériau MTL)
textured_mesh.export("model.obj")

# PLY (couleurs des sommets, compatible avec les nuages de points)
textured_mesh.export("model.ply")

Référence de performance

GPU	Forme (30 étapes)	Texture (20 étapes)	Total
RTX 4090	~20 s	~15 s	~35 s
RTX 3090	~30 s	~25 s	~55 s
A100 40 Go	~18 s	~12 s	~30 s

Conseils

• Supprimer les arrière-plans des images avant l'image vers 3D — utilisez rembg pour une segmentation propre

• Les prompts textuels bénéficient de la précision — « une épée médiévale low-poly avec poignée enveloppée de cuir » donne de meilleurs résultats que « épée »

• Réduisez num_inference_steps à 15–20 pour des aperçus plus rapides pendant l'itération

• Augmentez guidance_scale (8–12) pour une meilleure fidélité au prompt, au prix de la diversité

• GLB est le meilleur format d'export — il regroupe la géométrie, les textures et les matériaux dans un seul fichier

• Utilisez --share lors du lancement de Gradio sur Clore.ai pour l'accès distant via navigateur

• Les poids du modèle font ~15 Go — assurez-vous d'avoir suffisamment d'espace disque avant le premier lancement

• Pour les assets de jeu, générez en haute qualité puis décimez dans Blender pour les niveaux de LOD

Dépannage

Problème	Solution
Mémoire CUDA insuffisante	Utilisez une RTX 3090+ (24 Go). Réduisez la taille du lot ou les étapes d'inférence
Le téléchargement du modèle se bloque	Vérifiez l'espace disque. Utilisez huggingface-cli download tencent/Hunyuan3D-2 manuellement
Interface Gradio inaccessible	Passez --share l'indicateur, ou transférez le port 7860 depuis le tableau de bord Clore.ai
Qualité de géométrie médiocre	Augmentez num_inference_steps à 40+, essayez différentes graines
Artefacts de texture	Assurez-vous que le maillage de forme est propre avant l'étape de texture
Erreurs d'importation lors d'une nouvelle installation	Exécutez pip install -r requirements.txt à nouveau — certaines dépendances se compilent à partir du code स्रोत
Génération lente au premier lancement	Normal — la compilation du modèle et le chargement des poids sont mis en cache après la première inférence

Ressources

• GitHub de Hunyuan3D-2

• Modèle HuggingFace

• la place de marché CLORE.AI