Z Image Turbo Schnellstart für schnelle Text-zu-Bild-Generierung mit LoRA

Z Image Turbo ist auf Novita AI über zwei asynchrone Endpunkte verfügbar: POST https://api.novita.ai/v3/async/z-image-turbo für die Standard-Text-zu-Bild-Generierung und POST https://api.novita.ai/v3/async/z-image-turbo-lora für die Generierung mit LoRA-Stilmodellen. Beide folgen dem standardmäßigen asynchronen Muster von Novita AI – eine Anfrage senden, eine task_id erhalten, dann GET /v3/async/task-result abfragen, bis das Bild bereit ist. Diese Anleitung behandelt beide Endpunkte von Anfang bis Ende: erste Anfrage, Polling-Schleife, LoRA-Verwendung und die Parameterreferenz, die Sie benötigen, bevor Sie Produktionscode schreiben.

Wann Sie diesen Schnellstart verwenden sollten

Verwenden Sie diese Anleitung, wenn Sie eine verifizierte, funktionierende Anfrage für Z Image Turbo benötigen, bevor Sie Fehlerbehandlung, Batch-Verarbeitung oder Produktionslogik hinzufügen.

Z Image Turbo ist für hohen Durchsatz ausgelegt. Es passt zu Workflows, bei denen:

• Geschwindigkeit wichtiger ist als maximale Qualität – Prototyp-Pipelines, Batch-Vorschaugenerierung oder Echtzeitanwendungen, bei denen Latenz eine harte Einschränkung darstellt.
• Sie eine LoRA-basierte Stilübertragung wünschen, ohne den vollständigen txt2img-Parametersatz konfigurieren zu müssen. Der dedizierte LoRA-Endpunkt akzeptiert ein loras-Array und erledigt den Rest.
• Sie eine einfache Prompt-in/Bild-out-Schnittstelle mit einem minimalen Anforderungskörper benötigen.

Z Image Turbo ist nicht die richtige Wahl, wenn Sie die vollständige Konfigurationsfläche von Stable Diffusion benötigen – steps, guidance_scale, sampler_name, negative_prompt, hires_fix, Refiner-Modelle usw. Für diese Steuerungsebene verwenden Sie den Standard-Endpunkt POST /v3/async/txt2img.

Diese Anleitung behandelt nur den von Novita AI gehosteten API-Pfad. Sie befasst sich nicht mit Self-Hosting oder Feintuning.

Schritt 1: Holen Sie sich Ihren Novita-API-Schlüssel

Erstellen Sie ein Novita AI-Konto und navigieren Sie zur API-Schlüsselverwaltung. Generieren Sie einen Schlüssel und exportieren Sie ihn:

export NOVITA_API_KEY="your_api_key_here"

Bewahren Sie den Schlüssel außerhalb der Versionskontrolle, von Client-seitigen Bundles und Docker-Image-Ebenen auf.

Schritt 2: Bestätigen Sie die Endpunkte

Z Image Turbo auf Novita AI verwendet zwei separate Übermittlungsendpunkte und einen gemeinsamen Ergebnisendpunkt:

	Basis T2I	LoRA T2I
Übermittlung	POST https://api.novita.ai/v3/async/z-image-turbo	POST https://api.novita.ai/v3/async/z-image-turbo-lora
Ergebnisabfrage	GET https://api.novita.ai/v3/async/task-result?task_id=<id>	GET https://api.novita.ai/v3/async/task-result?task_id=<id>
API-Referenz	Z Image Turbo-Dokumentation	Z Image Turbo LoRA-Dokumentation

Beide Übermittlungsendpunkte geben nur eine task_id zurück. Der Ergebnisabfrage-Endpunkt ist für beide identisch – sobald Ihre Polling-Schleife für einen funktioniert, funktioniert sie auch für den anderen.

Schritt 3: Senden Sie Ihre erste Anfrage

Der Basisendpunkt erfordert prompt und size. Beginnen Sie hier, bevor Sie optionale Parameter hinzufügen:

curl -s -X POST https://api.novita.ai/v3/async/z-image-turbo \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic city skyline at dusk, neon lights, photorealistic, ultra-detailed",
    "size": "1024*1024"
  }'

Eine erfolgreiche 200-Antwort gibt Folgendes zurück:

{
  "task_id": "abc123..."
}

Speichern Sie die task_id. Bei der Übermittlung wird nichts anderes zurückgegeben – die Generierung läuft asynchron.

Zwei optionale Parameter sind am Basisendpunkt verfügbar:

• seed (Ganzzahl): Pin für reproduzierbare Ausgaben. Dieselbe Kombination aus Prompt und Seed liefert konsistente Ergebnisse.
• enable_base64_output (boolesch): Wenn true, enthält das Ergebnis das Bild als Base64-codierten String anstelle einer gehosteten URL.

Schritt 4: Pollen Sie das Ergebnis

Rufen Sie den Ergebnisabfrage-Endpunkt mit task_id als Abfrageparameter auf:

curl -s "https://api.novita.ai/v3/async/task-result?task_id=abc123..." \
  -H "Authorization: Bearer $NOVITA_API_KEY"

Eine abgeschlossene Aufgabe gibt Folgendes zurück:

{
  "task": {
    "task_id": "abc123...",
    "status": "TASK_STATUS_SUCCEED",
    "progress_percent": 100,
    "eta": 0
  },
  "images": [
    {
      "image_url": "https://...",
      "image_url_ttl": 3600,
      "image_type": "png"
    }
  ]
}

Pollen Sie alle 1–2 Sekunden, bis task.status entweder TASK_STATUS_SUCCEED oder TASK_STATUS_FAILED ist. Das Feld task.eta gibt eine geschätzte verbleibende Zeit in Sekunden an, wenn die Aufgabe noch in der Warteschlange ist.

image_url_ttl ist die Lebensdauer der URL in Sekunden. Laden Sie das Bild herunter und speichern Sie es, bevor die TTL abläuft – die gehostete URL ist nicht dauerhaft.

Schritt 5: Überprüfen Sie Preise, Limits und häufige Fehler

Die aktuellen Preise für Z Image Turbo sind auf der Preisseite von Novita AI und der Modellseite von Z Image Turbo aufgeführt. Überprüfen Sie die Tarife, bevor Sie Kosten abschätzen, da sich die Preise ändern können.

Häufige Fehler:

Fehler	Ursache	Behebung
401 Unauthorized	Fehlender oder fehlerhafter API-Schlüssel	Bestätigen Sie, dass der Header Authorization: Bearer <key> ist
400 Bad Request	Ungültiger Anforderungskörper	Bestätigen Sie, dass prompt und size Strings sind; seed muss eine Ganzzahl sein, falls angegeben
TASK_STATUS_FAILED	Generierung abgelehnt oder fehlerhaft	Lesen Sie task.reason in der Ergebnisantwort für die spezifische Fehlermeldung
Bild-URL gibt 403 zurück oder ist abgelaufen	URL nach Ablauf der TTL aufgerufen	Laden Sie das Bild herunter und speichern Sie es, bevor image_url_ttl Sekunden vergangen sind

Python-Beispiel

Vollständiger Workflow – übermitteln, pollern, Bild-URL zurückgeben:

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def generate_image(prompt: str, size: str = "1024*1024", seed: int = None) -> str:
    payload = {"prompt": prompt, "size": size}
    if seed is not None:
        payload["seed"] = seed

    resp = requests.post(
        "https://api.novita.ai/v3/async/z-image-turbo",
        json=payload,
        headers=HEADERS,
    )
    resp.raise_for_status()
    task_id = resp.json()["task_id"]

    while True:
        result = requests.get(
            f"https://api.novita.ai/v3/async/task-result?task_id={task_id}",
            headers=HEADERS,
        )
        result.raise_for_status()
        data = result.json()
        status = data["task"]["status"]

        if status == "TASK_STATUS_SUCCEED":
            return data["images"][0]["image_url"]
        if status == "TASK_STATUS_FAILED":
            raise RuntimeError(f"Generation failed: {data['task'].get('reason', 'unknown')}")

        time.sleep(1)

if __name__ == "__main__":
    url = generate_image(
        "A futuristic city skyline at dusk, neon lights, photorealistic",
        size="1024*1024",
        seed=42,
    )
    print(url)

LoRA-Generierung

Der LoRA-Endpunkt fügt der Anfrage ein loras-Array hinzu. Jeder Eintrag benötigt einen path (die LoRA-Modellkennung aus dem Novita AI-Modell-Hub) und einen scale (Einflussgewicht):

curl -s -X POST https://api.novita.ai/v3/async/z-image-turbo-lora \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a portrait in anime style, soft lighting, detailed face",
    "size": "768*1024",
    "loras": [
      {
        "path": "<lora-model-path>",
        "scale": 0.8
      }
    ],
    "seed": 42
  }'

Ersetzen Sie <lora-model-path> durch einen bestätigten Pfad aus dem Novita AI-Modell-Hub. Das path-Format und kompatible LoRA-Modelle sind in der Z Image Turbo LoRA-API-Referenz aufgeführt – raten Sie keine Modellpfade; verwenden Sie nur verifizierte Hub-Einträge, um TASK_STATUS_FAILED-Ergebnisse durch nicht auflösbare Pfade zu vermeiden.

Das Polling des LoRA-Ergebnisses funktioniert identisch zum Basisendpunkt.

Python-Version des gleichen LoRA-Workflows:

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def generate_with_lora(
    prompt: str,
    lora_path: str,
    lora_scale: float = 0.8,
    size: str = "1024*1024",
    seed: int = None,
) -> str:
    payload = {
        "prompt": prompt,
        "size": size,
        "loras": [{"path": lora_path, "scale": lora_scale}],
    }
    if seed is not None:
        payload["seed"] = seed

    resp = requests.post(
        "https://api.novita.ai/v3/async/z-image-turbo-lora",
        json=payload,
        headers=HEADERS,
    )
    resp.raise_for_status()
    task_id = resp.json()["task_id"]

    while True:
        result = requests.get(
            f"https://api.novita.ai/v3/async/task-result?task_id={task_id}",
            headers=HEADERS,
        )
        result.raise_for_status()
        data = result.json()
        status = data["task"]["status"]

        if status == "TASK_STATUS_SUCCEED":
            return data["images"][0]["image_url"]
        if status == "TASK_STATUS_FAILED":
            raise RuntimeError(f"Generation failed: {data['task'].get('reason', 'unknown')}")

        time.sleep(1)

LoRA-Skalenrichtlinien

scale steuert, wie stark der LoRA-Stil angewendet wird. Ein Wert von 0,8 ist ein sinnvoller Standardwert. Gehen Sie niedriger (0,4–0,6), wenn die Prompt-Details durch den LoRA-Stil überschrieben werden; gehen Sie höher (0,9–1,0), wenn der Stil nicht stark genug erscheint. Das Stapeln mehrerer LoRAs mit hohen Skalenwerten kann die Kohärenz beeinträchtigen – testen Sie jedes LoRA zuerst einzeln.

Einige LoRA-Modelle erfordern Triggerwörter im Prompt, um ihren Stil zu aktivieren. Überprüfen Sie die Modellauflistung im Novita AI-Hub auf erforderliche Schlüsselwörter, bevor Sie testen.

Wichtige Parameter

Basisendpunkt (/v3/async/z-image-turbo)

Parameter	Typ	Erforderlich	Beschreibung
prompt	string	Ja	Textbeschreibung des Zielbildes
size	string	Ja	Ausgabemaße als "Breite*Höhe", z.B. "1024*1024"
seed	integer	Nein	Reproduzierbarkeits-Pin; gleicher Seed + Prompt liefert konsistente Ausgaben
enable_base64_output	boolean	Nein	Wenn true, wird das Bild als Base64-String anstelle einer gehosteten URL zurückgegeben

LoRA-Endpunkt (/v3/async/z-image-turbo-lora)

Parameter	Typ	Erforderlich	Beschreibung
prompt	string	Ja	Text-Prompt; LoRA-Triggerwörter einschließen, falls erforderlich
size	string	Ja	Ausgabemaße als "Breite*Höhe"
loras	array	Ja	Ein oder mehrere LoRA-Objekte
loras[].path	string	Ja	LoRA-Modellpfad aus dem Novita AI-Modell-Hub
loras[].scale	number	Ja	Einflussgewicht; 0,8 ist ein üblicher Ausgangspunkt
seed	integer	Nein	Reproduzierbarkeits-Pin

enable_base64_output ist in der aktuellen Dokumentation nicht für den LoRA-Endpunkt aufgeführt. Verwenden Sie die Ergebnis-URL aus dem Polling zum Abrufen des Bildes.

Fehlerbehebung

Aufgabe bleibt länger als erwartet im Status TASK_STATUS_PENDING. Die Warteschlangentiefe variiert mit der Plattformlast. Das Feld task.eta in der Polling-Antwort gibt eine geschätzte Wartezeit in Sekunden zurück. Für latenzkritische Produktionspfade sollten Sie Anfragen parallel senden und über mehrere Aufgaben-IDs hinweg pollern.

TASK_STATUS_FAILED sofort oder nach kurzer Wartezeit. Lesen Sie task.reason im Ergebnis. Häufige Ursachen: ungültiges size-String-Format, ein nicht auflösbarer LoRA-path oder ein Prompt, der die Inhaltsfilterung ausgelöst hat. Isolieren Sie mit einer minimalen Anfrage.

Bild-URL gibt 403 zurück. Die URL-Lebensdauer wird durch image_url_ttl (in Sekunden) gesteuert. Wenn Sie die URL nach Ablauf dieses Zeitfensters anfordern, wird der Zugriff verweigert. Rufen Sie die Bilddaten sofort nach erfolgreichem Polling ab und speichern Sie sie.

LoRA-Stil erscheint nicht in der Ausgabe. Versuchen Sie, scale auf 1,0 zu erhöhen. Überprüfen Sie, ob das LoRA keine Triggerwörter erfordert – wenn doch, fügen Sie sie dem Prompt hinzu.

400 Bad Request am LoRA-Endpunkt. Stellen Sie sicher, dass das loras-Feld ein Array (kein Objekt) ist und dass sowohl path als auch scale in jedem Eintrag vorhanden sind.

FAQ

Wofür ist Z Image Turbo konzipiert?

Z Image Turbo ist für schnelle Text-zu-Bild-Generierung optimiert. Es eignet sich für Anwendungen, die schnellen Durchsatz benötigen: Vorschaugenerierung, Batch-Pipelines und Anwendungsfälle, bei denen die LoRA-basierte Stilisierung wichtiger ist als die feinkörnige Diffusionssteuerung eines vollständigen SDXL-Workflows.

Welche Größen unterstützt Z Image Turbo?

Der Parameter size nimmt einen String im Format "Breite*Höhe" entgegen. Bestätigte unterstützte Werte sind auf der Z Image Turbo-Modellseite aufgeführt. Quadratische (1024*1024) und Hochformat-Formate (768*1024) sind ein sicherer Ausgangspunkt, konsistent mit anderen Novita AI-Bildendpunkten.

Kann ich mehrere LoRAs in einer Anfrage anwenden?

Das loras-Array akzeptiert mehrere Einträge. In der Praxis verschlechtert das Stapeln von LoRAs mit hohen scale-Werten oft die Ausgabequalität. Testen Sie jedes LoRA zuerst einzeln und kombinieren Sie sie dann mit konservativen Skalenwerten (0,5–0,7 pro Eintrag).

Wo finde ich kompatible LoRA-Pfade?

Durchsuchen Sie den Novita AI-Modell-Hub und überprüfen Sie die Z Image Turbo LoRA-API-Referenz für das bestätigte Pfadformat. Verwenden Sie keine Pfade aus externen Quellen, ohne vorher zu überprüfen, ob sie auf der Novita-Plattform aufgelöst werden können.

Wird negative_prompt unterstützt?

Keiner der Z Image Turbo-Endpunkte listet in der aktuellen Dokumentation einen Parameter negative_prompt auf. Wenn Sie Motive oder Stile ausschließen müssen, verwenden Sie positive Formulierungen im Prompt, um von unerwünschten Inhalten wegzulenken, oder bewerten Sie den Standard-txt2img-Endpunkt, der negative_prompt direkt unterstützt.

Kann ich mehrere Bilder in einem einzigen Aufruf generieren?

Die aktuelle Dokumentation listet keinen Parameter image_num für einen der Z Image Turbo-Endpunkte auf. Für die Batch-Generierung senden Sie mehrere Anfragen parallel und pollern deren task_id-Werte gleichzeitig – jede Anfrage ist unabhängig.

Wie vergleicht sich Z Image Turbo mit dem Standard-txt2img-Endpunkt?

Der Standard-txt2img-Endpunkt unterstützt eine breite Konfigurationsfläche: Schritte, Guidance Scale, Sampler, negativer Prompt, Hi-Res-Fix und Refiner-Modelle. Z Image Turbo tauscht diese Konfigurierbarkeit gegen Geschwindigkeit und eine einfachere Anforderungsstruktur. Verwenden Sie txt2img, wenn die Parameterkontrolle wichtig ist; verwenden Sie Z Image Turbo, wenn Durchsatz oder Einfachheit Priorität haben.

Empfohlene Artikel

• Qwen Image Text-to-Image Schnellstart zur Generierung von Bildern aus Prompts
• FLUX.1 Kontext Pro vs Max vs Dev auf Novita AI
• LoRA Stable Diffusion hinzufügen: Ein umfassender Leitfaden