> 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/3d-generierung/hunyuan3d.md).

# Hunyuan3D 2.1

Generiere 3D-Meshes aus Text oder Bildern mit Tencent Hunyuan3D 2.1 auf Clore.ai

Hunyuan3D 2.1 von Tencent ist ein zweistufiges 3D-Generierungsmodell: Zuerst sagt es die Geometrie (Form) voraus, dann synthetisiert es PBR-Texturen. Es akzeptiert sowohl Text-Prompts als auch Referenzbilder als Eingabe und gibt produktionsreife Meshes im GLB-, OBJ- oder PLY-Format aus. Mit über 3 Millionen Downloads auf HuggingFace ist es eines der am weitesten verbreiteten Open-Source-3D-Generierungsmodelle.

{% hint style="success" %}
Alle Beispiele laufen auf GPU-Servern, die über die [CLORE.AI-Marktplatz](https://clore.ai/marketplace).
{% endhint %}

## Hauptfunktionen

* **Text-zu-3D und Bild-zu-3D** — beide Eingabemodi in einem einzigen Modell
* **Zweistufige Pipeline** — Formgenerierung gefolgt von PBR-Textursynthese
* **Ausgabe mit hoher Wiedergabetreue** — detaillierte Geometrie mit Albedo-, Normalen- und Rauigkeitskarten
* **Mehrere Exportformate** — GLB, OBJ, PLY
* **Gradio-Weboberfläche** — browserbasierte Interaktion, kein Code erforderlich
* **16–24 GB VRAM** — läuft auf RTX 3090 und RTX 4090
* **3 Mio.+ Downloads** auf HuggingFace — aktive Community und kontinuierliche Updates

## Anforderungen

| Komponente | Minimum        | Empfohlen      |
| ---------- | -------------- | -------------- |
| GPU        | RTX 3090 24 GB | RTX 4090 24 GB |
| VRAM       | 16 GB          | 24 GB          |
| RAM        | 16 GB          | 32 GB          |
| Festplatte | 50 GB          | 100 GB         |
| CUDA       | 12.8+          | 12.8+          |
| Python     | 3.10           | 3.11           |

**Clore.ai-Preise:** RTX 4090 ≈ 0,14–0,42 $/Std. · RTX 3090 ≈ 0,07–0,21 $/Std.

## Schnellstart

### 1. Klonen und installieren

```bash
git clone https://github.com/Tencent/Hunyuan3D-2.git
cd Hunyuan3D-2

# Umgebung erstellen
conda create -n hunyuan3d python=3.10 -y
conda activate hunyuan3d

# PyTorch installieren
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128

# Abhängigkeiten installieren
pip install -r requirements.txt

# Modellgewichte herunterladen (werden beim ersten Lauf automatisch heruntergeladen, insgesamt ca. 15 GB)
python -c "from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline; Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')"
```

### 2. Die Gradio-Weboberfläche starten

```bash
python gradio_app.py --port 7860 --share
```

Die Oberfläche bietet:

* Text-Eingabefeld für die Text-zu-3D-Generierung
* Bild-Upload für die Bild-zu-3D-Generierung
* Schieberegler für Inferenzschritte, Guidance-Scale und Seed
* 3D-Modellvorschau mit Orbit-Steuerung
* Download-Buttons für GLB/OBJ/PLY

### 3. Über die Python-API generieren

```python
from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline
from hy3dgen.texgen import Hunyuan3DPaintPipeline

# Phase 1: Formgenerierung
shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="shapegen",
)
shape_pipeline.to("cuda")

# Mesh aus Text generieren
mesh = shape_pipeline(
    prompt="ein detailliertes mittelalterliches Schwert mit kunstvollem Griff",
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

mesh.export("sword_shape.glb")
```

### 4. Texturen hinzufügen (Phase 2)

```python
# Phase 2: Textursynthese
texture_pipeline = Hunyuan3DPaintPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="texgen",
)
texture_pipeline.to("cuda")

textured_mesh = texture_pipeline(
    mesh=mesh,
    prompt="ein detailliertes mittelalterliches Schwert mit kunstvollem Griff",
    num_inference_steps=20,
    seed=42,
)[0]

textured_mesh.export("sword_textured.glb")
```

## Anwendungsbeispiele

### Bild-zu-3D-Generierung

```python
from PIL import Image

# Referenzbild laden
image = Image.open("reference_chair.png")

# Form aus Bild generieren
mesh = shape_pipeline(
    image=image,
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

# Textur anwenden
textured = texture_pipeline(
    mesh=mesh,
    image=image,
    num_inference_steps=20,
    seed=42,
)[0]

textured.export("chair.glb")
```

### Batch-Verarbeitung

```python
from pathlib import Path

prompts = [
    "ein roter Sportwagen, Low-Poly-Game-Asset",
    "eine hölzerne Schatztruhe, PBR-Material",
    "ein Sci-Fi-Helm mit Visier, Hard-Surface",
]

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"Erstellt: asset_{i:03d}.glb — {prompt[:40]}")
```

### In mehrere Formate exportieren

```python
# GLB (empfohlen — enthält Texturen, universelles Format)
textured_mesh.export("model.glb")

# OBJ (mit MTL-Materialdatei)
textured_mesh.export("model.obj")

# PLY (Vertex-Farben, mit Punktwolken kompatibel)
textured_mesh.export("model.ply")
```

## Leistungsreferenz

| GPU      | Geometrie (30 Schritte) | Textur (20 Schritte) | Gesamt    |
| -------- | ----------------------- | -------------------- | --------- |
| RTX 4090 | \~20 Sek.               | \~15 Sek.            | \~35 Sek. |
| RTX 3090 | \~30 Sek.               | \~25 Sek.            | \~55 Sek. |
| A100 40G | \~18 Sek.               | \~12 Sek.            | \~30 Sek. |

## Tipps

* **Bildehintergründe entfernen** vor Bild-zu-3D — verwende `rembg` für eine saubere Segmentierung
* **Text-Prompts profitieren von Spezifität** — „ein Low-Poly-mittelalterliches Schwert mit lederumwickeltem Griff“ liefert bessere Ergebnisse als „Schwert“
* **Reduziere `num_inference_steps`** auf 15–20 für schnellere Vorschauen während der Iteration
* **Erhöhen Sie `guidance_scale`** (8–12) für stärkere Einhaltung des Prompts auf Kosten der Vielfalt
* **GLB ist das beste Exportformat** — es bündelt Geometrie, Texturen und Materialien in einer einzigen Datei
* **Verwende `--share`** beim Starten von Gradio auf Clore.ai für den Remote-Browserzugriff
* **Modellgewichte sind ca. 15 GB groß** — stelle vor dem ersten Lauf ausreichend Speicherplatz sicher
* **Für Game-Assets**, mit hoher Qualität generieren und dann in Blender für LOD-Stufen reduzieren

## Fehlerbehebung

| Problem                                | Lösung                                                                                                         |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `CUDA-Speicher erschöpft`              | Verwende RTX 3090+ (24 GB). Verringere die Batch-Größe oder die Inferenzschritte                               |
| Modelldownload hängt fest              | Prüfe den Speicherplatz. Verwende `huggingface-cli download tencent/Hunyuan3D-2` manuell                       |
| Gradio-Oberfläche nicht erreichbar     | Übergebe `--share` den --share-Schalter oder leite Port 7860 vom Clore.ai-Dashboard weiter                     |
| Schlechte Geometriequalität            | Erhöhen Sie `num_inference_steps` auf 40+, probiere verschiedene Seeds                                         |
| Texturartefakte                        | Stelle sicher, dass das Shape-Mesh vor der Texturphase sauber ist                                              |
| Importfehler bei frischer Installation | Ausführen `pip install -r requirements.txt` erneut — einige Abhängigkeiten werden aus dem Quellcode kompiliert |
| Langsame Generierung beim ersten Lauf  | Erwartet — Modellkompilierung und das Laden der Gewichte werden nach der ersten Inferenz zwischengespeichert   |

## Ressourcen

* [Hunyuan3D-2 GitHub](https://github.com/Tencent/Hunyuan3D-2)
* [HuggingFace-Modell](https://huggingface.co/tencent/Hunyuan3D-2)
* [CLORE.AI-Marktplatz](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-de/3d-generierung/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.