> 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

HunyuanImage 3.0 von Tencent ist das **weltweit größte Open-Source-Bildgenerierungsmodell** mit insgesamt 80 Mrd. Parametern (13 Mrd. aktiv während der Inferenz). Veröffentlicht am 26. Januar 2026, bricht es mit Konventionen, 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 elementerhaltende Bearbeitungen durch, beherrscht Stilübertragungen und sogar Multibilderfusion, alles mit nur einem 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 & kommerzielle Nutzung unter 100M MAU)

## Hauptmerkmale

* **80 Mrd. insgesamt / 13 Mrd. aktive Parameter** — größtes Open-Source-Bild-MoE-Modell; aktiviert pro Inferenz nur 13 Mrd. Parameter
* **Einheitliche multimodale Architektur** — Text-zu-Bild, Bildbearbeitung, Stiltransfer und Mehrbildkomposition in einem Modell
* **Anleitungsgetriebene Bearbeitung** — beschreibe in natürlicher Sprache, was du geändert haben möchtest, dabei werden unveränderte Elemente bewahrt
* **Verdichteter 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                               | Einsatzgebiet                         | 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

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

**Empfohlene Clore.ai-Konfiguration:**

* **Bestes Preis-Leistungs-Verhältnis:** 1× A100 80GB (\~$2–4/Tag) — läuft bequem mit dem vollständigen Modell ohne Offloading
* **Budget-Option:** 1× RTX 4090 (\~$0.5–2/Tag) — funktioniert mit CPU-Offloading (langsamer, aber funktionsfähig)
* **Schnelle Produktion:** 2× A100 80GB (\~$4–8/Tag) — 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/cu121

# 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 (erfordert ~80GB VRAM für Vollpräzision)
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 erzeugen
prompt = "Ein ruhiger japanischer Garten im Herbst, Koi schwimmen in einem kristallklaren Teich, goldene Ahornblätter fallen, Aquarell-Malstil"
output = model.generate_image(prompt, num_inference_steps=30)
output.save("japanese_garden.png")
```

### Verwendung der Gradio-Weboberfläche

Die einfachste Möglichkeit, mit allen Funktionen zu experimentieren:

```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 einen SSH-Tunnel zugreifen: `ssh -L 7860:localhost:7860 root@<clore-ip>`

## Beispielanwendungen

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

```bash
cd HunyuanImage-3.0

python inference.py \
    --model-path ./ckpts/HunyuanImage-3-Instruct \
    --prompt "Cyberpunk-Stadtbild bei Nacht, neonbeleuchtete Wolkenkratzer spiegeln sich in regengetränkten 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 — bearbeite vorhandene Bilder, indem du die Ä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 distillierten Modell (8 Schritte)

```bash
# Distillierten 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 einem Pferd auf dem Mars reitet, fotorealistisch" \
    --output-path astronaut.png \
    --num-inference-steps 8
```

## Vergleich mit anderen Bildmodellen

| Funktion               | HunyuanImage 3.0     | FLUX.2 Klein           | SD 3.5 Groß            |
| ---------------------- | -------------------- | ---------------------- | ---------------------- |
| Parameter              | 80B MoE (13B aktiv)  | 32B DiT                | 8B DiT                 |
| Architektur            | Autoregressives MoE  | Diffusions-Transformer | Diffusions-Transformer |
| Bildbearbeitung        | ✅ Native             | ❌ Benötigt ControlNet  | ❌ Benötigt img2img     |
| Mehrbildfusion         | ✅ Native             | ❌                      | ❌                      |
| Stiltransfer           | ✅ Native             | ❌ Benötigt LoRA        | ❌ Benötigt LoRA        |
| Min. VRAM              | \~24GB (ausgelagert) | 16GB                   | 8GB                    |
| 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 distillierte Modell für Geschwindigkeit** — `HunyuanImage-3.0-Instruct-Distil` generiert in 8 Schritten statt 30–50 und reduziert die Inferenzzeit um das 4–6-fache. Die Qualität bleibt überraschend nahe am vollständigen Modell.
2. **A100 80GB ist der Sweet Spot** — Eine einzelne A100 80GB (\~$2–4/Tag auf Clore.ai) betreibt das Instruct-Modell ohne Offloading-Tricks. Das ist deutlich schneller als eine RTX 4090 mit CPU-Offloading.
3. **Modelle vorab herunterladen** — Der vollständige Instruct-Checkpoint ist \~160GB. Lade ihn einmal auf ein persistenten Clore.ai-Volume herunter, um ein erneutes Herunterladen bei jedem Start einer neuen Instanz zu vermeiden.
4. **Verwende SSH-Tunneling für Gradio** — Setze Port 7860 nicht öffentlich aus. Verwende `ssh -L 7860:localhost:7860` um sicher aus deinem Browser auf die Weboberfläche zuzugreifen.
5. **Probiere das vLLM-Backend für Batch-Arbeiten** — Wenn du viele Bilder generierst, bietet der vLLM-Inferenzpfad (im `vllm_infer/` Ordner) deutlich bessere Durchsatzraten.

## Fehlerbehebung

| Problem                                        | Lösung                                                                                                                              |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `CUDA out of memory` auf RTX 4090              | Verwenden Sie `device_map="auto"` um CPU-Offloading zu aktivieren, oder wechsle zum Distil-Modell                                   |
| Download schlägt fehl / sehr langsam           | Setze `HF_TOKEN` als Umgebungsvariable; verwende `huggingface-cli download` mit `--resume-download`                                 |
| Kann Modell nicht über HF-Modell-ID laden      | Aufgrund des Punkts im Namen zuerst lokal klonen: `huggingface-cli download tencent/HunyuanImage-3.0-Instruct --local-dir ./ckpts/` |
| Verschwommene oder niedrigqualitative Ausgaben | Erhöhen Sie `--num-inference-steps` auf 40–50; erhöhe `--guidance-scale` auf 7.0                                                    |
| Bildbearbeitung ignoriert Anweisungen          | Sei spezifisch darüber, was geändert und was erhalten werden soll; verwende kurze, klare Prompts                                    |
| Gradio-Oberfläche startet nicht                | Stelle sicher, dass `gradio>=4.0` installiert ist; überprüfe, dass 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
* [Distillierter Checkpoint](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct-Distil) — 8-Schritt schnelle Inferenz
* [Technischer Bericht (arXiv)](https://arxiv.org/pdf/2509.23951) — Architekturdetails und Benchmarks
* [ComfyUI-Integration](https://github.com/bgreene2/ComfyUI-Hunyuan-Image-3) — Community ComfyUI benutzerdefinierter Knoten


---

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