ZIMAGETURBO_SETUP.md

Z-Image Turbo Integration für PixelForge

Schritt 1: Google Colab Setup

1. Öffne pixelforge_colab_test.ipynb in Google Colab

2. Führe alle Cells aus:

   • Dependencies installieren
   • GPU-Check
   • Modell laden (Colab T4 = ~2-3 Min)
   • API-Server starten

3. Ngrok einrichten (für Public URL):

   # Registriere dich auf ngrok.com (kostenlos)
   # Kopiere Auth-Token in Colab Cell 5
   

Schritt 2: PixelForge konfigurieren

Setze diese Umgebungsvariablen vor dem Backend-Start:

$env:ZIMAGETURBO_API_URL = "https://dein-ngrok-url.ngrok.io"  # Colab Public URL
$env:ZIMAGETURBO_API_KEY = ""  # Leer, wenn keine Auth benötigt
$env:ZIMAGETURBO_TIMEOUT = "300"  # 5 Minuten

Beispiel (Windows PowerShell):

cd "d:/VSC Codes/Bild/imageforge"
$env:ZIMAGETURBO_API_URL = "https://abc123.ngrok.io"
& "D:/VSC Codes/Bild/.venv/Scripts/python.exe" -m backend.app.main

Schritt 3: Backend-Start

Backend wird neu gestartet und Z-Image Turbo sollte verfügbar sein:

[2026-02-20 12:34:56] ✓ Z-Image Turbo API verfügbar: https://abc123.ngrok.io

Schritt 4: Im UI verwenden

1. Öffne http://127.0.0.1:5173/
2. Wechsle das Modell zu "Z-Image Turbo"
3. Gib einen Prompt ein und klicke "Generate"
4. Das Bild wird über Colab generiert ☁️

Lokale Installation (statt Colab)

Wenn du Z-Image Turbo lokal installieren möchtest:

# 1. Download & Install
pip install z-image-turbo torch diffusers

# 2. Lokaler API-Server (optional)
from flask import Flask
from z_image_turbo import Pipeline

app = Flask(__name__)
pipe = Pipeline("zimageturbo-fast")  # Oder dein Modell

@app.route('/health', methods=['GET'])
def health():
    return {"status": "ok"}

@app.route('/generate', methods=['POST'])
def generate():
    # ... generiere Bild ...
    pass

Dann: ZIMAGETURBO_API_URL=http://localhost:5000

Tipps & Troubleshooting

Problem	Lösung
API antwortet nicht	Ngrok-URL in Colab und Env-Var prüfen
Timeout (300s zu kurz)	ZIMAGETURBO_TIMEOUT=600 erhöhen
Colab-Session beendet	Notebook neu starten (Ngrok-Token erforderlich)
"Unknown provider"	Backend Cache leeren: killall python + Neustart

Performance

Setup	Speed	Kosten
Colab + T4	30-60s/Bild	Kostenlos
Lokal (RTX 4070)	5-10s/Bild	~€500
RunPod (A100)	2-3s/Bild	€0.50-1.00/h

---

Viel Spaß mit Z-Image Turbo! 🚀