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

# HunyuanImage 3.0

Führe HunyuanImage 3.0 aus — Tencents 80B MoE multimodales Bildgenerierungs- und Bearbeitungsmodell auf Clore.ai-GPUs

HunyuanImage 3.0 von Tencent ist das **weltweit größte Open-Source-Bildgenerierungsmodell** mit 80B Parametern insgesamt (13B aktiv während der Inferenz). Veröffentlicht am 26. Januar 2026, bricht es mit dem üblichen Muster, indem es Bildgenerierung, Bearbeitung und Verständnis in einem einzigen autoregressiven Modell vereint — keine separaten Pipelines mehr für Text-zu-Bild und Bild-zu-Bild. Es erzeugt fotorealistische Bilder, führt präzise Bearbeitungen unter Beibehaltung der Elemente durch, unterstützt Stilübertragungen und macht sogar Mehrbild-Fusion — alles mit einem einzigen Modell.

**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) **Lizenz:** Tencent Hunyuan Community License (kostenlos für Forschung und kommerzielle Nutzung unter 100 Mio. MAU)

## Hauptfunktionen

* **80B Parameter insgesamt / 13B aktive Parameter** — größtes Open-Source-Bild-MoE-Modell; aktiviert pro Inferenz nur 13B Parameter
* **Einheitliche multimodale Architektur** — Text-zu-Bild, Bildbearbeitung, Stilübertragung und Mehrbild-Komposition in einem Modell
* **Anweisungsgesteuerte Bearbeitung** — beschreibe in natürlicher Sprache, was geändert werden soll, und bewahre unveränderte Elemente
* **Destillierter Checkpoint verfügbar** — `HunyuanImage-3.0-Instruct-Distil` läuft in nur 8 Sampling-Schritten für schnellere Generierung
* **vLLM-Beschleunigung** — native vLLM-Unterstützung für deutlich schnellere Inferenz in der Produktion
* **Autoregressives Framework** — im Gegensatz zu DiT-basierten Modellen (FLUX, SD3.5) verwendet es einen einheitlichen AR-Ansatz für Verständnis und Generierung

## Modellvarianten

| Modell                               | Anwendungsfall                        | Schritte | HuggingFace                                |
| ------------------------------------ | ------------------------------------- | -------- | ------------------------------------------ |
| **HunyuanImage-3.0**                 | Nur Text-zu-Bild                      | 30–50    | `tencent/HunyuanImage-3.0`                 |
| **HunyuanImage-3.0-Instruct**        | Text-zu-Bild + Bearbeitung + Mehrbild | 30–50    | `tencent/HunyuanImage-3.0-Instruct`        |
| **HunyuanImage-3.0-Instruct-Distil** | Schnelle Inferenz (8 Schritte)        | 8        | `tencent/HunyuanImage-3.0-Instruct-Distil` |

## Anforderungen

{% hint style="warning" %}
**Multi-GPU-Rigs der 80GB-Klasse sind auf dem Clore.ai-Marktplatz nicht gelistet.** Die größten heute gelisteten Systeme sind 4× RTX PRO 6000 Blackwell (je 96 GB, 380 GB gesamt) und 8–11× RTX 5090 (je 32 GB). Kapazitäten für A100 / H200 / B200 werden als [Bare Metal](https://clore.ai/bare-metal) auf Anfrage verkauft. Prüfe [GPU-Preise & Verfügbarkeit](/guides/guides_v2-de/erste-schritte/pricing.md) bevor du eine Bereitstellung dimensionierst.
{% endhint %}

| Konfiguration | Eine GPU (Offloading)    | Empfohlen    | Multi-GPU-Produktion |
| ------------- | ------------------------ | ------------ | -------------------- |
| GPU           | 1× RTX 4090 24GB         | 1× A100 80GB | 2–3× A100 80GB       |
| VRAM          | 24GB (mit Layer-Offload) | 80 GB        | 160–240GB            |
| RAM           | 128 GB                   | 128 GB       | 256 GB               |
| Festplatte    | 200GB                    | 200GB        | 200GB                |
| CUDA          | 12.8+                    | 12.8+        | 12.8+                |

**Empfohlene Clore.ai-Einrichtung:**

* **Das beste Preis-Leistungs-Verhältnis auf dem Marktplatz:** 1× RTX PRO 6000 Blackwell 96GB ($0.92–1.38/Stunde) — läuft das vollständige Modell bequem ohne Offloading. Eine A100 80GB ist die klassische Wahl, ist aber nur verfügbar als [Bare Metal](https://clore.ai/bare-metal)
* **Budget-Option:** 1× RTX 4090 ($0.14–0.42/Stunde) — funktioniert mit CPU-Offloading (langsamer, aber funktionsfähig)
* **Schnelle Produktion:** 2× A100 80GB ([Bare Metal](https://clore.ai/bare-metal)) — für Batch-Generierung und das Instruct-Modell

## Schnellstart

### Installation

```bash
# Repository klonen
git clone https://github.com/Tencent-Hunyuan/HunyuanImage-3.0.git
cd HunyuanImage-3.0

# Umgebung erstellen
pip install -r requirements.txt
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128

# Modellgewichte herunterladen
huggingface-cli download tencent/HunyuanImage-3.0-Instruct --local-dir ./ckpts/HunyuanImage-3-Instruct
```

### Text-zu-Bild mit Transformers

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

# Modell laden (für volle Präzision werden ~80GB VRAM benötigt)
model_path = "./ckpts/HunyuanImage-3-Instruct"
model = AutoModelForCausalLM.from_pretrained(
    model_path,
    torch_dtype=torch.bfloat16,
    device_map="auto",
    trust_remote_code=True,
)

# Ein Bild aus Text generieren
prompt = "Ein ruhiger japanischer Garten im Herbst, Koi-Fische schwimmen in einem kristallklaren Teich, goldene Ahornblätter fallen, Aquarellmalstil"
output = model.generate_image(prompt, num_inference_steps=30)
output.save("japanese_garden.png")
```

### Die Gradio-Weboberfläche verwenden

Der einfachste Weg, alle Funktionen auszuprobieren:

```bash
cd HunyuanImage-3.0

# Gradio installieren
pip install gradio

# Weboberfläche starten
python gradio_demo.py \\
    --model-path ./ckpts/HunyuanImage-3-Instruct \\
    --server-name 0.0.0.0 \\
    --server-port 7860
```

Dann über SSH-Tunnel zugreifen: `ssh -L 7860:localhost:7860 root@<clore-ip>`

## Anwendungsbeispiele

### 1. Text-zu-Bild-Generierung (CLI)

```bash
cd HunyuanImage-3.0

python inference.py \
    --model-path ./ckpts/HunyuanImage-3-Instruct \\
    --prompt "Cyberpunk-Stadtlandschaft bei Nacht, neonbeleuchtete Wolkenkratzer spiegeln sich in regennassen Straßen, fliegende Autos, volumetrischer Nebel, 8K" \\
    --output-path output.png \\
    --num-inference-steps 30 \\
    --guidance-scale 5.0
```

### 2. Bildbearbeitung mit natürlicher Sprache

Eine der herausragenden Funktionen von HunyuanImage 3.0 — bestehende Bilder bearbeiten, indem du Änderungen beschreibst:

```bash
python inference.py \
    --model-path ./ckpts/HunyuanImage-3-Instruct \\
    --prompt "Ändere die Jahreszeit zu Winter mit Schnee, der die Bäume bedeckt" \\
    --image-path input_photo.jpg \\
    --output-path edited_winter.png \\
    --num-inference-steps 30
```

### 3. Schnelle Generierung mit dem destillierten Modell (8 Schritte)

```bash
# Destillierten Checkpoint herunterladen
huggingface-cli download tencent/HunyuanImage-3.0-Instruct-Distil \\
    --local-dir ./ckpts/HunyuanImage-3-Instruct-Distil

# Mit nur 8 Schritten generieren (5–6× schneller)
python inference.py \
    --model-path ./ckpts/HunyuanImage-3-Instruct-Distil \\
    --prompt "Porträt eines Astronauten, der auf dem Mars auf einem Pferd reitet, fotorealistisch" \\
    --output-path astronaut.png \\
    --num-inference-steps 8
```

## Vergleich mit anderen Bildmodellen

| Funktion               | HunyuanImage 3.0     | FLUX.2 Klein           | SD 3.5 Large           |
| ---------------------- | -------------------- | ---------------------- | ---------------------- |
| Parameter              | 80B MoE (13B aktiv)  | 32B DiT                | 8B DiT                 |
| Architektur            | Autoregressives MoE  | Diffusions-Transformer | Diffusions-Transformer |
| Bildbearbeitung        | ✅ Nativ              | ❌ Erfordert ControlNet | ❌ Erfordert img2img    |
| Mehrbild-Fusion        | ✅ Nativ              | ❌                      | ❌                      |
| Stilübertragung        | ✅ Nativ              | ❌ Erfordert LoRA       | ❌ Erfordert LoRA       |
| Min. VRAM              | \~24GB (ausgelagert) | 16 GB                  | 8 GB                   |
| Geschwindigkeit (A100) | \~15–30 Sek.         | \~0,3 Sek.             | \~5 Sek.               |
| Lizenz                 | Tencent-Community    | Apache 2.0             | Stability AI CL        |

## Tipps für Clore.ai-Nutzer

1. **Verwende das destillierte Modell für Geschwindigkeit** — `HunyuanImage-3.0-Instruct-Distil` generiert in 8 Schritten statt 30–50 und verkürzt die Inferenzzeit um das 4–6-Fache. Die Qualität bleibt überraschend nah am Vollmodell.
2. **Eine 96-GB-Karte ist der Sweet Spot** — Eine einzelne RTX PRO 6000 Blackwell (oder eine A100 80GB via [Bare Metal](https://clore.ai/bare-metal)) — Der vollständige Instruct-Checkpoint ist \~160GB. Lade ihn einmal auf ein persistentes Clore.ai-Volume herunter, um zu vermeiden, dass er bei jedem Start einer neuen Instanz erneut heruntergeladen werden muss.
3. **Modelle vorab herunterladen** — Der vollständige Instruct-Checkpoint ist \~160GB. Lade ihn einmal auf ein persistentes Clore.ai-Volume herunter, um zu vermeiden, dass er bei jedem Start einer neuen Instanz erneut heruntergeladen werden muss.
4. **SSH-Tunneling für Gradio verwenden** — Lege Port 7860 nicht öffentlich offen. Verwende `ssh -L 7860:localhost:7860` um die Weboberfläche sicher in deinem Browser aufzurufen.
5. **Probiere das vLLM-Backend für Batch-Arbeiten aus** — Wenn du viele Bilder erzeugst, bietet der vLLM-Inferenzpfad (im `vllm_infer/` Ordner) deutlich besseren Durchsatz.

## Fehlerbehebung

| Problem                                                | Lösung                                                                                                                              |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `CUDA-Speicher erschöpft` auf der RTX 4090             | Verwende `device_map="auto"` um CPU-Offloading zu aktivieren, oder wechsle zum Distil-Modell                                        |
| Download schlägt fehl / sehr langsam                   | Setze `HF_TOKEN` Umgebungsvariable; verwende `huggingface-cli download` mit `--resume-download`                                     |
| Modell kann nicht über die HF-Modell-ID geladen werden | Aufgrund des Punkts im Namen zuerst lokal klonen: `huggingface-cli download tencent/HunyuanImage-3.0-Instruct --local-dir ./ckpts/` |
| Unscharfe oder minderwertige Ausgaben                  | Erhöhen Sie `--num-inference-steps` auf 40–50; erhöhe `--guidance-scale` auf 7.0                                                    |
| Bildbearbeitung ignoriert Anweisungen                  | Sei konkret, was geändert und was beibehalten werden soll; verwende kurze, klare Prompts                                            |
| Gradio-Oberfläche startet nicht                        | Stelle sicher `gradio>=4.0` installiert ist; prüfe, ob der Modellpfad auf das richtige Verzeichnis zeigt                            |

## Weiterführende Lektüre

* [GitHub-Repository](https://github.com/Tencent-Hunyuan/HunyuanImage-3.0) — offizieller Code, Inferenzskripte, Gradio-Demo
* [HunyuanImage 3.0-Instruct (HuggingFace)](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct) — vollständige Modellgewichte
* [Destillierter Checkpoint](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct-Distil) — schnelle Inferenz in 8 Schritten
* [Technischer Bericht (arXiv)](https://arxiv.org/pdf/2509.23951) — Architekturdetails und Benchmarks
* [ComfyUI-Integration](https://github.com/bgreene2/ComfyUI-Hunyuan-Image-3) — Community-Custom-Node für 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-de/bildgenerierung/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.