E-Commerce-Produktbilder mit z-image über die hiapi API generieren

Die meisten Bildmodelle können ein Produkt zeichnen. Aber nur sehr wenige können das Produkt gut zeichnen und gleichzeitig den Preis korrekt buchstabieren. Im E-Commerce – Preisschilder, Aktionsbanner, Rabattkarten, Verpackungsetiketten – ist der Text im Bild entscheidend, und ein einziges verunstaltetes Zeichen bedeutet, dass das Asset abgelehnt wird.

z-image ist ein Text-zu-Bild-Modell der Turbo-Klasse auf hiapi, das genau für dieses Nischen-Szenario entwickelt wurde: schnelle Erzeugung fotorealistischer Bilder, präziser Text im Bild (Englisch und Chinesisch), zum Preis von $0.008 pro Bild – weniger als ein Drittel des Preises der meisten Alternativen. Jedes Bild in diesem Leitfaden wurde mit exakt demselben Prompt generiert, der daneben angezeigt wird, über denselben /v1/tasks-Aufruf, den du weiter unten kopieren kannst, wobei jede Renderung Ende-zu-Ende etwa 30–60 Sekunden dauert.

Warum z-image für Produktbilder wählen

Für eine E-Commerce-Pipeline sind drei Eigenschaften wichtig, und z-image glänzt in allen drei:

• Textwiedergabe. Wenn man die unten beschriebenen Prompt-Regeln befolgt, kommen Aktionskarten, Versandbanner und Flaschenetiketten mit jedem Wort korrekt buchstabiert zurück.
• Geschwindigkeit. Dies ist ein Turbo-optimiertes Modell; unsere Testrenderings wurden jedes Mal in deutlich weniger als einer Minute fertig, sodass die Stapelverarbeitung von Hunderten von SKU-Bildern in der Zeit erledigt ist, in der man einen Kaffee trinkt.
• Preis. Bei $0.008/Bild (auf der Preisseite verifiziert) kostet die Aktualisierung eines Katalogs mit 1.000 Bildern $8. Dieselbe Aufgabe mit gpt-image-2 ($0.03/Bild) würde $30 kosten.

Wenn du einen umfassenderen Überblick über das Modell möchtest – Einrichtung des API-Schlüssels, allgemeine Beispiele, wann man es nicht verwenden sollte – lies Z-Image API: Preise, API-Schlüssel, Beispiele und Anwendungsfälle. Dieser Leitfaden konzentriert sich auf E-Commerce-Workflows.

Verifizierte API-Schnittstelle

z-image läuft auf dem asynchronen Task-Endpunkt von hiapi. Du reichst eine Aufgabe ein, pollst sie bis zum Erfolg und lädst dann die Ausgabe herunter. Wir haben zwei Schema-Fakten gegen die Live-API bestätigt (beide unterscheiden sich von einigen anderen Modellen auf der Plattform):

1. input akzeptiert nur prompt und aspect_ratio. Das Senden eines resolution-Feldes gibt HTTP 400 zurück (additional properties not allowed) – anders als bei gpt-image-2, das dieses Feld erfordert.
2. aspect_ratio muss einer der Werte 1:1, 4:3, 3:4, 16:9, 9:16 sein. Jeder andere Wert (wir haben 3:2 ausprobiert) wird mit 400 abgelehnt, zusammen mit einer Auflistung der gültigen Werte.

Die Ausgabeauflösung ist proportional festgelegt – unsere Renderings kamen als PNG zurück: 1536×1536 (1:1), 1344×768 (16:9), 928×1232 (3:4) und 1728×1296 (4:3).

Aufgabe einreichen

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image",
    "input": {
      "prompt": "Studio-Produktfoto für E-Commerce: eine matt schwarze isolierte Edelstahl-Wasserflasche vor einem nahtlosen hellgrauen Hintergrund...",
      "aspect_ratio": "1:1"
    }
  }'

Die Antwort enthält eine Task-ID:

{"code": 200, "data": {"taskId": "tk-hiapi-01KWGHSXWH8J1Z2CADYNQQ8GDG"}}

Abpollern und herunterladen

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWGHSXWH8J1Z2CADYNQQ8GDG \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Poll alle paar Sekunden, bis data.status success ist und data.output vorhanden ist; betrachte fail als Endzustand. Ein nützlicher Hinweis: Kurz nach der Generierung meldet die Aufgabe möglicherweise kurzzeitig einen Zwischenzustand (wir haben archiving beobachtet), bevor das output-Array erscheint; daher sollte deine Schleife auf das Vorhandensein der Ausgabe-URL prüfen, nicht nur auf den Status-String.

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def generate(prompt: str, ratio: str = "1:1") -> bytes:
    r = requests.post(API, headers=HEADERS, json={
        "model": "z-image",
        "input": {"prompt": prompt, "aspect_ratio": ratio},
    }, timeout=60)
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 300
    while time.time() < deadline:
        task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        output = task.get("output") or []
        if output and output[0].get("url"):
            return requests.get(output[0]["url"], timeout=120).content
        if task.get("status") == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(5)
    raise TimeoutError(task_id)

png = generate("...dein Produkt-Prompt...", "1:1")
open("product.png", "wb").write(png)

Sofort herunterladen. output[0].url ist ein temporärer Link mit einem expireAt-Zeitstempel – speichere die Bytes unmittelbar nach erfolgreicher Aufgabe dauerhaft in deinem eigenen Speicher (S3/R2/CDN). Wenn eine Aufgabe hängen zu bleiben scheint, hier wird erklärt, wie man hängende oder abgelaufene hiapi-Aufgaben diagnostiziert.

Fünf E-Commerce-Rezepte mit echten Ausgaben

Alle folgenden Bilder sind echte z-image-Renderings, die mit exakt den angegebenen Prompts generiert wurden. Ohne jede Nachbearbeitung.

1. Hauptbild mit Preisschild

Studio-Produktfoto für E-Commerce: eine matt schwarze isolierte Edelstahl-Wasserflasche
zentriert vor einem nahtlosen hellgrauen Hintergrund mit weichem Schatten. Eine rechteckige
korallfarbene Papierkarte lehnt an der Flasche. Die Karte enthält NUR diese beiden Zeilen
fetter, sauberer serifenloser Schrift und keine anderen Wörter: "SUMMER SALE" in der
ersten Zeile, "$19.99" in der zweiten Zeile. Text flach zur Kamera, groß, perfekt lesbar.
Fotorealistisch.

Achte auf die Formulierung: Der anzuzeigende Text steht in Anführungszeichen, und der Prompt besagt, dass die Karte nur diese Wörter enthält. In unserem ersten Versuch beschrieben wir den Text inline („...reads exactly: SUMMER SALE on the first line and $19.99 on the second line“), und das Modell setzte das Wort „ON“ getreu zwischen die beiden Zeilen – Anweisungswörter sickerten in das Rendering durch. Setze wörtliche Strings in Anführungszeichen; halte die Anweisungen außerhalb der Anführungszeichen.

2. Breites Aktionsbanner

Breites E-Commerce-Promobanner, fotorealistisches Flat-Lay von weißen Sneakers und einem
Versandkarton aus Kraftpapier vor pastellblauem Hintergrund. Auf der rechten Seite fetter
dunkelblauer serifenloser Text mit genau diesen vier Wörtern und diesem Betrag, sonst
nichts: "FREE SHIPPING OVER $50". Alle vier Wörter müssen erscheinen. Text groß, gerade,
perfekt lesbar. Saubere kommerzielle Studiobeleuchtung.

16:9 liefert dir ein Banner mit 1344×768, das direkt in den Hero-Bereich deines Shop-Startseite passt.

3. Vertikale Rabattkarte für soziale Medien

Vertikale Produktkarte für soziale Medien: eine kleine braune Kosmetik-Pipettenflasche aus
Glas auf einem warmen beigen Podest, weiches Tageslicht. Über der Flasche liest eine fette
schwarze moderne serifenlose Überschrift exakt: 30% OFF TODAY ONLY. Text flach zur Kamera,
groß und perfekt lesbar. Minimalistischer Premium-E-Commerce-Stil, fotorealistisch.

3:4 (928×1232) ist das Format, das einem Feed-Post am nächsten kommt; wenn deine Plattform es verlangt, kannst du es nachgelagert auf 4:5 zuschneiden.

4. Lesbares Verpackungsetikett

Makro-E-Commerce-Produktfoto einer Hautpflegeflasche aus Milchglas mit einem sauberen
weißen Etikett. Der Etikettentext, gedruckt in eleganter dunkler serifenloser Schrift,
liest exakt: GLOW SERUM in der ersten Zeile und VITAMIN C 10% in der zweiten Zeile.
Frontale Ansicht, Etikett vollständig sichtbar und scharf, weiche Studiobeleuchtung,
fotorealistisch, weißer Hintergrund.

Dies war der schwierigste Test in dieser Gruppe – kleine Schrift auf gebogenem Glas – und das Etikett kam sauber zurück, einschließlich „10%“.

5. Farbkollektion (ohne Text)

Katalogfoto für E-Commerce: drei identische Keramik-Kaffeetassen nebeneinander von links
nach rechts in Salbeigrün, Terrakotta-Orange und Marineblau, vor einem schlichten weißen
Studiohintergrund mit weichen, gleichmäßigen Schatten. Nirgendwo im Bild Text.
Fotorealistisch, konsistente Produktgeometrie bei allen drei Tassen.

Die konsistente Geometrie zwischen den Varianten ist genau das, was sie als Katalogstreifen brauchbar macht – z-image hielt die drei farbigen Tassen in einer einzigen Generierung exakt gleich geformt.

Prompt-Regeln, damit Text überlebt

Kondensiert aus dem, was in unseren tatsächlichen Läufen funktioniert hat (und was nicht):

1. Setze wörtliche Strings in Anführungszeichen. text reads exactly: "SUMMER SALE" – das Modell behandelt die umgebenden Wörter ohne Anführungszeichen als Kandidaten-Copy.
2. Füge „and no other words“ (und keine anderen Wörter) hinzu. Andernfalls erfindet das Modell möglicherweise zusätzliche Badge-Texte, um den Platz zu füllen.
3. Halte den Text frontal zur Kamera. Unser einziges verunstaltetes Rendering war Text, der schräg an einem Anhänger hing; derselbe Text auf einer flachen Karte war perfekt. Perspektivische Verzerrung ist der Ort, an dem Glyphen zuerst zusammenbrechen.
4. Ein bis zwei Textblöcke pro Bild. Jeder zusätzliche Textblock vervielfacht die Ausfallwahrscheinlichkeit; für komplexe Layouts setze sie nachgelagert zusammen.
5. Vor der Veröffentlichung prüfen. Bei diesem Preis kannst du dir eine Retry-Schleife leisten: rendern, Text per OCR oder Sichtprüfung kontrollieren, bei Nichtübereinstimmung neu generieren. Selbst mit einem Retry pro fehlgeschlagenem Bild sind die Kosten nur ein Bruchteil der Alternativmodelle.

Kosten im Stapelbetrieb

Ein konkretes Szenario: 200 SKUs × 3 Assets pro SKU (Produktlistenbild, Aktionsbanner, Social-Media-Karte) = 600 Bilder.

Modell	Preis/Bild	600 Bilder	Anmerkungen
z-image	$0.008	$4.80	Turbo-Geschwindigkeit, stark bei Text im Bild
flux-schnell	$0.005	$3.00	Am günstigsten, aber kein Fokus auf Textwiedergabe
qwen-image-2.0	$0.025	$15.00	Starke Allzweckqualität
gpt-image-2	$0.03	$18.00	Erfordert das resolution-Feld; E-Commerce-Leitfaden hier

(Preise von der hiapi-Preisseite zum Zeitpunkt der Veröffentlichung.)

Der Stapelmodus besteht einfach darin, die obige generate()-Funktion in eine Schleife zu stecken – reiche eine kleine Anzahl von Aufgaben gleichzeitig ein, sammle die Task-IDs und poll sie dann in Gruppen ab. Wenn du stark skalieren willst, lies zuerst wie hiapi mit Rate-Limits und Burst-Traffic umgeht.

Erste Schritte

Hol dir einen API-Schlüssel aus deiner Konsole und richte dann die obigen Code-Snippets auf deinen eigenen Produktkatalog – die z-image-Modellseite hat die Modellkarte, und die hiapi-Dokumentation beschreibt die Task-API umfassend. Bei $0.008 pro Rendering ist die günstigste Art herauszufinden, ob es zu deiner Pipeline passt, deine zehn schwierigsten SKUs noch heute Nachmittag durchlaufen zu lassen.