> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-fr/generation-3d/hunyuan3d.md).

# Hunyuan3D 2.1

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.

{% hint style="success" %}
Tous les exemples s'exécutent sur des serveurs GPU loués via le [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

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

```bash
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

```bash
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

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

```python
# É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

```python
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

```python
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

```python
# 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](https://github.com/Tencent/Hunyuan3D-2)
* [Modèle HuggingFace](https://huggingface.co/tencent/Hunyuan3D-2)
* [CLORE.AI Marketplace](https://clore.ai/marketplace)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/guides_v2-fr/generation-3d/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.