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 (forme), puis synthétise des textures PBR. Il accepte à la fois des invites textuelles et des images de référence en entrée et produit des maillages prêts pour la production aux formats 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 le CLORE.AI Marketplace.

Principales caractéristiques

• Texte en 3D et image en 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, normales et rugosité

• Formats d'export multiples — GLB, OBJ, PLY

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

• 16–24 GB 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 GB	RTX 4090 24 Go
VRAM	16 Go	24 Go
RAM	16 Go	32 Go
Disque	50 Go	100 Go
CUDA	11.8	12.1+
Python	3.10	3.11

Tarifs Clore.ai : RTX 4090 ≈ 0,5–2 $/jour · RTX 3090 ≈ 0,3–1 $/jour

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/cu121

# 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 propose :

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

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

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

• Aperçu du modèle 3D avec contrôles 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 des textures (Étape 2)

# Étape 2 : synthèse de 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→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 low-poly pour jeu",
    "un coffre au trésor en bois, matériau PBR",
    "un casque sci-fi 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 vers 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 nuage 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 sec	~55 s
A100 40G	~18 s	~12 s	~30 s

Conseils

• Supprimer les arrière-plans d'image avant image→3D — utiliser rembg pour une segmentation propre

• Les invites textuelles bénéficient de la spécificité — "une épée médiévale low-poly avec poignée en cuir" produit de meilleurs résultats que "épée"

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

• Augmentez guidance_scale (8–12) pour une adhérence plus forte à l'invite au prix de la diversité

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

• Utilisez --share lors du lancement de Gradio sur Clore.ai pour un 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écimatez dans Blender pour les niveaux de LOD

Dépannage

Problème	Solution
CUDA out of memory	Utilisez RTX 3090+ (24 GB). Réduisez la taille de lot ou les étapes d'inférence
Le téléchargement du modèle bloque	Vérifiez l'espace disque. Utilisez huggingface-cli download tencent/Hunyuan3D-2 manuellement
Interface Gradio inaccessible	Passer --share le drapeau, ou rediriger le port 7860 depuis le tableau de bord Clore.ai
Qualité de géométrie médiocre	Augmentez num_inference_steps à 40+, essayez d'autres graines
Artéfacts de texture	Assurez-vous que le maillage de la forme est propre avant l'étape de texture
Erreurs d'import sur une installation fraîche	Exécutez pip install -r requirements.txt à nouveau — certaines dépendances se compilent depuis les sources
Génération lente au premier lancement	Attendu — la compilation du modèle et le chargement des poids sont mis en cache après la première inférence

Ressources

• Hunyuan3D-2 GitHub

• Modèle HuggingFace

• CLORE.AI Marketplace