# 🚀 Z-Image Turbo - Schnellstart für PixelForge

## ⏱️ 5 Minuten Installation & Test

### 1️⃣ Google Colab Vorbereitung (2 Min)

```bash
# 1. Gehe zu https://colab.research.google.com
# 2. Wähle: File → Open notebook → Upload
# 3. Wähle: pixelforge_colab_test.ipynb
# 4. Runtime → Change runtime type → GPU (T4)
# 5. Registriere bei https://ngrok.com (kostenlos)
# 6. Kopiere Auth Token aus Account Settings
```

### 2️⃣ Colab Notebook Ausführen (2 Min)

```python
# Cell 1: Abhängigkeiten installieren
# → Drücke Shift+Enter zum Ausführen

# Cell 2: GPU-Check
# → Sollte zeigen: "GPU T4 erkannt ✓"

# Cell 3: Modell laden
# → Lädt Stable Diffusion (ca. 2 GB)

# Cell 4: Test-Generierung
# → Generiert ein Testbild (~30 Sekunden)

# Cell 5: API-Server starten
# → Ersetze "YOUR_NGROK_TOKEN" mit deinem Token
# → Drücke Ausführen & kopiere Public URL
# → Z.B.: https://abc123def456.ngrok.io
```

### 3️⃣ PixelForge Starten (1 Min)

**Option A: PowerShell (Empfohlen)**
```powershell
cd "d:\VSC Codes\Bild"
.\start_zimageturbo.ps1
# → Gebe Colab Ngrok-URL ein
```

**Option B: Batch-Datei**
```cmd
cd d:\VSC Codes\Bild
start_zimageturbo.bat
# → Gebe Colab Ngrok-URL ein
```

### 4️⃣ Terminal-Befehle (Manuell)

```powershell
# Backend
cd "d:\VSC Codes\Bild\imageforge"
$env:ZIMAGETURBO_API_URL = "https://abc123def456.ngrok.io"
$env:ZIMAGETURBO_TIMEOUT = "300"
& "D:/VSC Codes/Bild/.venv/Scripts/python.exe" -m backend.app.main

# Separate PowerShell Tab:
cd "d:\VSC Codes\Bild\imageforge\frontend"
npm run dev:web
```

### 5️⃣ Im Browser Testen

```
1. Öffne: http://127.0.0.1:5173
2. Wähle "Z-Image Turbo" im Modell-Dropdown
3. Gib Prompt ein: "A beautiful sunset over mountains"
4. Klicke "Generate"
5. Warte 30-60 Sekunden
6. Bild sollte in Browser erscheinen ✓
```

---

## ✅ Checkliste

- [ ] Colab-Konto aktiviert & GPU eingeschaltet
- [ ] ngrok-Account registriert & Auth Token kopiert
- [ ] pixelforge_colab_test.ipynb in Colab hochgeladen
- [ ] Alle 5 Cells im Notebook ausgeführt
- [ ] Ngrok Public URL kopiert (z.B. https://abc123.ngrok.io)
- [ ] start_zimageturbo.ps1 oder .bat ausgeführt
- [ ] ZIMAGETURBO_API_URL korrekt gesetzt
- [ ] Backend läuft: http://127.0.0.1:8008/health (sollte OK sein)
- [ ] Frontend läuft: http://127.0.0.1:5173 (sollte React-UI zeigen)
- [ ] Test-Generierung abgeschlossen (echtes Bild!)

---

## 🆘 Häufige Probleme

| Problem | Lösung |
|---------|--------|
| "API nicht erreichbar" | Colab noch am Laden? Oder Ngrok Token ungültig? |
| "Timeout nach 300s" | Colab-Model zu lange zum Laden? Timeout erhöhen: `$env:ZIMAGETURBO_TIMEOUT = "600"` |
| "Colab-Sitzung verloren" | Google Colab beendet nach 4h Leerlauf. Notebook neu starten! |
| "Port 5173 bereits in Verwendung" | Alte Vite instanz lauft noch: `Get-Process -Name "node" \| Stop-Process` |
| "Fehler: Unknown Provider" | Backend neu starten nach Env-Variablen-Änderung! |

---

## 📊 Performance erwartet

| Hardware | Zeit | Qualität |
|----------|------|----------|
| Colab T4 GPU | 30-60s | High ⭐⭐⭐ |
| Lokal tiny-sd | 5-10s | Medium ⭐⭐ |
| i9 + RTX 4070 | 5-10s | High ⭐⭐⭐ |
| RunPod A100 | 2-3s | Ultra ⭐⭐⭐⭐ |

---

## 🔧 Umgebungsvariablen

```powershell
# Manuell (falls nicht über Skript):
$env:ZIMAGETURBO_API_URL = "https://deine-ngrok-url.ngrok.io"
$env:ZIMAGETURBO_TIMEOUT = "300"          # Sekunden
$env:ZIMAGETURBO_PROXY = ""               # Optional für Proxy

# Oder permanent in Windows:
# Systemsteuerung → Umgebungsvariablen → Neue Var hinzufügen
```

---

## 🌐 Alternative: Lokale Installation (Ohne Colab)

```bash
# Wenn du Z-Image Turbo lokal installieren möchtest:
# 1. Lade Modell von HuggingFace herunter
# 2. Starte lokalen Flask-Server (ähnlich Colab-Notebook)
# 3. Setze ZIMAGETURBO_API_URL auf http://localhost:5000
```

---

## 📝 Mehrere Modelle testen

Im ZIMAGETURBO_SETUP.md gibt es weitere Optionen:
- **Stable Diffusion v1.5** (schnell, gut)
- **Stable Diffusion XL** (langsam, sehr gut)
- **Custom Models** von HuggingFace

Ändere einfach im Colab Cell 3 das Modell!

---

## 💡 Tipps

1. **Colab bleibt aktiv**: Öffne DevTools (F12) → Keep console open
2. **Bessere Prompts**: Nutze Details wie "4K, professional, highly detailed"
3. **Batch-Generierung**: Mehrere Prompts nacheinander → Job-Queue
4. **Speichern**: Generierte Bilder landen in output/YYYY-MM-DD/job_*/

---

## ❓ Mehr Hilfe

- **Technisches**: Siehe [ZIMAGETURBO_SETUP.md](ZIMAGETURBO_SETUP.md)
- **Provider Code**: [zimageturbo_provider.py](imageforge/backend/app/providers/zimageturbo_provider.py)
- **Colab-Notebook**: [pixelforge_colab_test.ipynb](pixelforge_colab_test.ipynb)

---

**Viel Spaß beim Testen! 🎨✨**