> 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

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.

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

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

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

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

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

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

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

```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 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](https://github.com/Tencent/Hunyuan3D-2)
* [Modèle HuggingFace](https://huggingface.co/tencent/Hunyuan3D-2)
* [la place de marché CLORE.AI](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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.