> 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-dimages/hunyuan-image3.md).

# HunyuanImage 3.0

Exécutez HunyuanImage 3.0 — le modèle multimodal de génération et d'édition d'images MoE 80B de Tencent sur les GPU Clore.ai

HunyuanImage 3.0 de Tencent est le **le plus grand modèle open source de génération d’images au monde** avec 80 B de paramètres au total (13 B actifs pendant l’inférence). Lancé le 26 janvier 2026, il sort des sentiers battus en unifiant la génération d’images, l’édition et la compréhension dans un seul modèle autorégressif — plus besoin de pipelines séparés pour le texte vers image et l’image vers image. Il génère des images photoréalistes, effectue des modifications précises en préservant les éléments, gère les transferts de style et réalise même la fusion de plusieurs images, le tout à partir d’un seul modèle.

**HuggingFace :** [tencent/HunyuanImage-3.0-Instruct](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct) **GitHub :** [Tencent-Hunyuan/HunyuanImage-3.0](https://github.com/Tencent-Hunyuan/HunyuanImage-3.0) **Licence :** Licence communautaire Tencent Hunyuan (gratuite pour la recherche et l’usage commercial sous 100 M d’utilisateurs actifs mensuels (MAU))

## Caractéristiques clés

* **80 B paramètres au total / 13 B actifs** — plus grand modèle MoE open source d’images ; n’active que 13 B de paramètres par inférence
* **Architecture multimodale unifiée** — texte vers image, édition d’images, transfert de style et composition multi-images dans un seul modèle
* **Édition guidée par instructions** — décrivez ce que vous voulez modifier en langage naturel, en préservant les éléments intacts
* **Point de contrôle distillé disponible** — `HunyuanImage-3.0-Instruct-Distil` s’exécute en seulement 8 étapes d’échantillonnage pour une génération plus rapide
* **Accélération vLLM** — prise en charge native de vLLM pour une inférence nettement plus rapide en production
* **Cadre autorégressif** — contrairement aux modèles basés sur DiT (FLUX, SD3.5), utilise une approche AR unifiée pour la compréhension et la génération

## Variantes de modèle

| Modèle                               | Cas d’utilisation                        | Étapes | HuggingFace                                |
| ------------------------------------ | ---------------------------------------- | ------ | ------------------------------------------ |
| **HunyuanImage-3.0**                 | Texte vers image uniquement              | 30–50  | `tencent/HunyuanImage-3.0`                 |
| **HunyuanImage-3.0-Instruct**        | Texte vers image + édition + multi-image | 30–50  | `tencent/HunyuanImage-3.0-Instruct`        |
| **HunyuanImage-3.0-Instruct-Distil** | Inférence rapide (8 étapes)              | 8      | `tencent/HunyuanImage-3.0-Instruct-Distil` |

## Exigences

{% hint style="warning" %}
**Les configurations multi-GPU de classe 80 Go ne sont pas répertoriées sur la place de marché Clore.ai.** Les plus grosses machines répertoriées aujourd’hui sont 4× RTX PRO 6000 Blackwell (96 Go chacune, 380 Go au total) et 8–11× RTX 5090 (32 Go chacune). La capacité A100 / H200 / B200 est proposée en bare metal sur demande. Consultez [bare metal](https://clore.ai/bare-metal) sur demande. Consultez [Tarifs et disponibilité des GPU](/guides/guides_v2-fr/premiers-pas/pricing.md) avant de dimensionner un déploiement.
{% endhint %}

| Configuration | GPU unique (déchargement)            | Recommandé    | Production multi-GPU |
| ------------- | ------------------------------------ | ------------- | -------------------- |
| GPU           | 1× RTX 4090 24 Go                    | 1× A100 80 Go | 2–3× A100 80 Go      |
| VRAM          | 24 Go (avec déchargement de couches) | 80 Go         | 160–240 Go           |
| RAM           | 128 Go                               | 128 Go        | 256GB                |
| Disque        | 200 Go                               | 200 Go        | 200 Go               |
| CUDA          | 12.8+                                | 12.8+         | 12.8+                |

**Configuration Clore.ai recommandée :**

* **Meilleur rapport qualité-prix sur la place de marché :** 1× RTX PRO 6000 Blackwell 96 Go (0,92–1,38 $/h) — exécute confortablement le modèle complet sans déchargement. Une A100 80 Go est le choix classique, mais elle n’est disponible que comme [bare metal](https://clore.ai/bare-metal)
* **Option économique :** 1× RTX 4090 (0,14–0,42 $/h) — fonctionne avec le déchargement CPU (plus lent, mais opérationnel)
* **Production rapide :** 2× A100 80 Go ([bare metal](https://clore.ai/bare-metal)) — pour la génération par lots et le modèle Instruct

## Démarrage rapide

### Installation

```bash
# Cloner le dépôt
git clone https://github.com/Tencent-Hunyuan/HunyuanImage-3.0.git
cd HunyuanImage-3.0

# Créer l’environnement
pip install -r requirements.txt
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128

# Télécharger les poids du modèle
huggingface-cli download tencent/HunyuanImage-3.0-Instruct --local-dir ./ckpts/HunyuanImage-3-Instruct
```

### Texte vers image avec Transformers

```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

# Charger le modèle (nécessite environ 80 Go de VRAM en précision complète)
model_path = "./ckpts/HunyuanImage-3-Instruct"
model = AutoModelForCausalLM.from_pretrained(
    model_path,
    torch_dtype=torch.bfloat16,
    device_map="auto",
    trust_remote_code=True,
)

# Générer une image à partir du texte
prompt = "Un jardin japonais serein en automne, des carpes koï nageant dans un étang d’une clarté cristalline, des feuilles d’érable dorées tombant, style peinture aquarelle"
output = model.generate_image(prompt, num_inference_steps=30)
output.save("japanese_garden.png")
```

### Utilisation de l’interface Web Gradio

La façon la plus simple d’expérimenter avec toutes les fonctionnalités :

```bash
cd HunyuanImage-3.0

# Installer Gradio
pip install gradio

# Lancer l’interface web
python gradio_demo.py \\
    --model-path ./ckpts/HunyuanImage-3-Instruct \\
    --server-name 0.0.0.0 \\
    --server-port 7860
```

Puis accédez-y via un tunnel SSH : `ssh -L 7860:localhost:7860 root@<clore-ip>`

## Exemples d'utilisation

### 1. Génération texte vers image (CLI)

```bash
cd HunyuanImage-3.0

python inference.py \\
    --model-path ./ckpts/HunyuanImage-3-Instruct \\
    --prompt "Paysage urbain cyberpunk la nuit, gratte-ciel illuminés au néon reflétés dans des rues trempées par la pluie, voitures volantes, brouillard volumétrique, 8K" \\
    --output-path output.png \\
    --num-inference-steps 30 \\
    --guidance-scale 5.0
```

### 2. Édition d’images en langage naturel

L’une des fonctionnalités phares de HunyuanImage 3.0 — modifiez des images existantes en décrivant les changements :

```bash
python inference.py \\
    --model-path ./ckpts/HunyuanImage-3-Instruct \\
    --prompt "Changer la saison en hiver avec de la neige recouvrant les arbres" \\
    --image-path input_photo.jpg \\
    --output-path edited_winter.png \\
    --num-inference-steps 30
```

### 3. Génération rapide avec le modèle distillé (8 étapes)

```bash
# Télécharger le point de contrôle distillé
huggingface-cli download tencent/HunyuanImage-3.0-Instruct-Distil \\
    --local-dir ./ckpts/HunyuanImage-3-Instruct-Distil

# Générer avec seulement 8 étapes (5 à 6× plus rapide)
python inference.py \\
    --model-path ./ckpts/HunyuanImage-3-Instruct-Distil \\
    --prompt "Portrait d’un astronaute chevauchant un cheval sur Mars, photoréaliste" \\
    --output-path astronaut.png \\
    --num-inference-steps 8
```

## Comparaison avec d’autres modèles d’images

| Fonctionnalité      | HunyuanImage 3.0       | FLUX.2 Klein              | SD 3.5 Large                          |
| ------------------- | ---------------------- | ------------------------- | ------------------------------------- |
| Paramètres          | MoE 80 B (13 B actifs) | DiT 32 B                  | DiT 8 B                               |
| Architecture        | MoE autorégressif      | Transformeur de diffusion | Transformeur de diffusion             |
| Édition d’images    | ✅ Natif                | ❌ Nécessite ControlNet    | ❌ Nécessite img2img                   |
| Fusion multi-images | ✅ Natif                | ❌                         | ❌                                     |
| Transfert de style  | ✅ Natif                | ❌ Nécessite LoRA          | ❌ Nécessite LoRA                      |
| VRAM minimale       | \~24 Go (déchargé)     | 16 Go                     | 8 Go                                  |
| Vitesse (A100)      | \~15–30 s              | \~0,3 s                   | \~5 s                                 |
| Licence             | Communauté Tencent     | Apache 2.0                | Licence communautaire de Stability AI |

## Conseils pour les utilisateurs de Clore.ai

1. **Utilisez le modèle distillé pour la rapidité** — `HunyuanImage-3.0-Instruct-Distil` génère en 8 étapes au lieu de 30–50, réduisant le temps d’inférence de 4 à 6×. La qualité reste étonnamment proche de celle du modèle complet.
2. **Une carte 96 Go est le juste milieu** — une seule RTX PRO 6000 Blackwell (ou une A100 80 Go via [bare metal](https://clore.ai/bare-metal)) exécute le modèle Instruct sans aucune astuce de déchargement. C’est beaucoup plus rapide qu’une RTX 4090 avec déchargement CPU.
3. **Pré-téléchargez les modèles** — le point de contrôle Instruct complet fait environ 160 Go. Téléchargez-le une fois sur un volume Clore.ai persistant pour éviter de le retélécharger à chaque nouvelle instance.
4. **Utilisez un tunnel SSH pour Gradio** — n’exposez pas le port 7860 publiquement. Utilisez `ssh -L 7860:localhost:7860` pour accéder à l’interface web en toute sécurité depuis votre navigateur.
5. **Essayez le backend vLLM pour le traitement par lots** — si vous générez beaucoup d’images, le chemin d’inférence vLLM (dans le `vllm_infer/` dossier) offre un débit nettement meilleur.

## Dépannage

| Problème                                              | Solution                                                                                                                                      |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `Mémoire CUDA insuffisante` sur RTX 4090              | Utilisez `device_map="auto"` pour activer le déchargement CPU, ou passez au modèle Distil                                                     |
| Échec du téléchargement / très lent                   | Définissez `HF_TOKEN` la variable d’environnement ; utilisez `huggingface-cli download` avec `--resume-download`                              |
| Impossible de charger le modèle via l’ID du modèle HF | En raison du point dans le nom, clonez d’abord localement : `huggingface-cli download tencent/HunyuanImage-3.0-Instruct --local-dir ./ckpts/` |
| Sorties floues ou de faible qualité                   | Augmentez `--num-inference-steps` à 40–50 ; augmentez `--guidance-scale` à 7,0                                                                |
| L’édition d’images ignore les instructions            | Soyez précis sur ce qu’il faut modifier et ce qu’il faut préserver ; utilisez des prompts courts et clairs                                    |
| L’interface Gradio ne se lance pas                    | Assurez-vous que `gradio>=4.0` est installé ; vérifiez que le chemin du modèle pointe vers le bon répertoire                                  |

## Pour aller plus loin

* [Dépôt GitHub](https://github.com/Tencent-Hunyuan/HunyuanImage-3.0) — code officiel, scripts d’inférence, démo Gradio
* [HunyuanImage 3.0-Instruct (HuggingFace)](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct) — poids complets du modèle
* [Point de contrôle distillé](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct-Distil) — inférence rapide en 8 étapes
* [Rapport technique (arXiv)](https://arxiv.org/pdf/2509.23951) — détails de l’architecture et benchmarks
* [Intégration ComfyUI](https://github.com/bgreene2/ComfyUI-Hunyuan-Image-3) — nœud personnalisé communautaire ComfyUI


---

# 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-dimages/hunyuan-image3.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.