E-Commerce-Produktbilder mit FLUX.1 [schnell] über die hiapi API generieren

Katalogfotografie ist der langsamste Schritt beim Online-Stellen einer SKU. Studio buchen, Stylisten engagieren, Softbox aufbauen, Retuscheur beauftragen – für eine Tasse, die $24 kostet, ergibt das überhaupt keinen Sinn. flux-schnell/text-to-image auf hiapi liefert dir brauchbare Produktbilder mit weißem Hintergrund, Szenen-Hero-Bilder und Farb-/Materialvarianten für $0.005 pro Bild, Ende-zu-Ende in etwa 30 Sekunden – bei dieser Größenordnung machst du dir keine Gedanken mehr über die Kosten pro Aufnahme, sondern über Prompts und Prompt-Batches.

Dieser Leitfaden geht den genauen Workflow durch: die vier Bildtypen, die eine Produktdetailseite tatsächlich braucht; die Prompt-Struktur, die das Modell auf einem sauberen, nahtlosen Hintergrund hält, statt einen Holztisch zu erfinden; wie du 100 Varianten über /v1/tasks stapelweise generierst, ohne dein Terminal zu überlasten; und die wenigen Dinge, die schnell nicht kann und die du im Voraus einplanen musst.

Warum Katalogarbeit besonders gut zu flux-schnell passt

Auf hiapi gibt es auch treuere Modelle (flux-2, flux-1.1-pro, nano-banana-pro), und für das eine Hero-Bild einer Markenkampagne solltest du diese verwenden. Für den Katalog rechnet es sich aber anders:

• Ein Launch mit 200 SKUs, jeweils etwa 4 Bilder (Freisteller, Szene, Größenreferenz, Draufsicht) = 800 Bilder. Bei $0.005 sind das $4. Bei $0.05 sind es $40. Bei $0.17 sind es $136.
• schnell schließt die Generierung in 1–4 Sampling-Schritten ab, sodass Ende-zu-Ende (Warteschlange + Generierung + Download) in unseren Läufen etwa 30 Sekunden dauert. flux-2 und nano-banana-pro sind um ein Vielfaches langsamer.
• Katalogbilder werden auf Produktdetailseiten mit 600px Breite angezeigt, in Rastern mit 200px. Bei diesen Größen ist der Treue-Vorsprung der Premium-Modelle schlicht nicht sichtbar; Prompt-Treue und eine sinnvolle Seitenverhältnis-Wahl sind wichtiger.

Der Kompromiss ist real: schnell ist schwach bei kleinem lesbarem Text auf Etiketten, schwach bei Produkten in menschlicher Hand (nutze dafür nano-banana-pro) und deutlich schwach bei komplexen Markenlogos. Für „zeig mir das Produkt auf sauberem Hintergrund, in drei Farben, von oben und in Dreiviertelansicht“ – also seine eigentliche Kernaufgabe – ist es hervorragend.

Die Bildliste, die du tatsächlich generierst

Bevor du irgendeinen Prompt schreibst, lege fest, was dein Produktdetailseiten-Template braucht. Ein nützliches Startsortiment:

Bildtyp	Seitenverhältnis	Verwendung
Produktbild auf weißem Hintergrund	1:1	Hauptbild der Produktdetailseite, Raster-Vorschaubilder
Studio-Aufnahme in Dreiviertelansicht	4:3	2. Bild der Produktdetailseiten-Galerie
Szenen-/Kontextbild	3:2	Produktdetailseiten-Galerie, Social Ads
Draufsicht-Flatlay	1:1	Produktdetailseiten-Galerie, Größenreferenz
Raster der Farb-/Materialvarianten	je Variante 1:1	Vorschaubilder des Farbwählers

flux-schnell auf hiapi unterstützt 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 21:9, auto. Jedes andere Verhältnis wird beim Erstellen der Aufgabe abgelehnt.

Einmaliger Lauf: ein einzelnes Produktbild mit curl generieren

Das Minimum, um zu bestätigen, dass der Token funktioniert. Mein letzter Lauf dauerte Ende-zu-Ende 31 Sekunden:

TOKEN="$HIAPI_API_KEY"

# 1. 创建任务
TASK=$(curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-schnell/text-to-image",
    "input": {
      "prompt": "Product packshot: matte ceramic coffee mug, soft beige glaze, centered on seamless white cyclorama, soft diffused studio lighting, subtle contact shadow, 50mm photography, no props, ecommerce hero, clean negative space top and bottom",
      "aspect_ratio": "1:1"
    }
  }' | jq -r '.data.taskId')

echo "task: $TASK"

# 2. 轮询直到完成（success | fail）
while true; do
  STATE=$(curl -s "https://api.hiapi.ai/v1/tasks/$TASK" \
    -H "Authorization: Bearer $TOKEN")
  STATUS=$(echo "$STATE" | jq -r '.data.status')
  echo "  status=$STATUS"
  [ "$STATUS" = "success" ] && break
  [ "$STATUS" = "fail" ] && { echo "$STATE" | jq '.data.error'; exit 1; }
  sleep 4
done

# 3. 下载（输出 URL 会过期；要立刻抓取）
URL=$(echo "$STATE" | jq -r '.data.output[0].url')
curl -s -o packshot.jpg "$URL"
echo "saved packshot.jpg"

Eine Besonderheit, die bei flux-schnell besonders zu beachten ist: Das Input-Schema dieses Modells akzeptiert aspect_ratio, lehnt aber resolution ab. Andere Bildmodelle auf hiapi (z. B. flux-2, nano-banana-pro) akzeptieren beides. Wenn du an flux-schnell {"aspect_ratio": "1:1", "resolution": "1K"} sendest, erhältst du:

{
  "code": 400,
  "message": "additional properties not allowed: resolution"
}

Entferne resolution. Du brauchst es nicht – schnell gibt in dem von dir gewählten Seitenverhältnis in der Standardgröße des Modells aus.

Produktivbetrieb: stapelweise Generierung mit Python

Echte Katalogarbeit übermittelt viele Aufgaben, lädt Ausgaben herunter, sobald sie fertig sind, und wiederholt fehlgeschlagene Fälle. Dies ist das Skript, das wir beim Prototyping für eine SKU-Reihe verwendet haben:

"""Batch packshot generator for flux-schnell on hiapi.

Reads a CSV of (sku, prompt, aspect_ratio), submits all jobs, polls in parallel,
downloads finished outputs to ./out/{sku}.jpg. Total cost = $0.005 * len(csv).
"""
import csv
import json
import os
import subprocess
import time
from concurrent.futures import ThreadPoolExecutor, as_completed
from pathlib import Path

API = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]
OUT = Path("./out"); OUT.mkdir(exist_ok=True)


def _post(path, body):
    r = subprocess.run(
        ["curl", "-s", "-X", "POST", path,
         "-H", f"Authorization: Bearer {TOKEN}",
         "-H", "Content-Type: application/json",
         "-d", json.dumps(body)],
        capture_output=True, text=True, timeout=60,
    )
    return json.loads(r.stdout)


def _get(path):
    r = subprocess.run(
        ["curl", "-s", path, "-H", f"Authorization: Bearer {TOKEN}"],
        capture_output=True, text=True, timeout=30,
    )
    return json.loads(r.stdout)


def render(sku: str, prompt: str, ratio: str) -> tuple[str, str]:
    """Submit → poll → download. Returns (sku, status). status='ok' or 'fail:<reason>'."""
    body = {"model": "flux-schnell/text-to-image",
            "input": {"prompt": prompt, "aspect_ratio": ratio}}
    resp = _post(API, body)
    task_id = (resp.get("data") or {}).get("taskId")
    if not task_id:
        return sku, f"fail:submit:{resp.get('message')}"

    deadline = time.time() + 180
    while time.time() < deadline:
        state = _get(f"{API}/{task_id}")
        data = state.get("data") or {}
        status = data.get("status")
        if status == "success":
            url = (data.get("output") or [{}])[0].get("url")
            if not url:
                return sku, "fail:no-output-url"
            subprocess.run(["curl", "-s", "-o", str(OUT / f"{sku}.jpg"), url],
                           timeout=60, check=True)
            return sku, "ok"
        if status == "fail":
            return sku, f"fail:model:{data.get('error', {}).get('code')}"
        time.sleep(4)
    return sku, "fail:timeout"


def main():
    rows = list(csv.DictReader(open("skus.csv")))
    print(f"submitting {len(rows)} renders (cost ${0.005 * len(rows):.3f})")
    with ThreadPoolExecutor(max_workers=8) as ex:
        futures = {ex.submit(render, r["sku"], r["prompt"], r["aspect_ratio"]): r
                   for r in rows}
        for f in as_completed(futures):
            sku, status = f.result()
            print(f"  {sku}: {status}")


if __name__ == "__main__":
    main()

Eine Zeile in skus.csv sieht so aus:

sku,prompt,aspect_ratio
mug-beige-01,"Product packshot: matte ceramic mug, beige glaze, seamless white cyclorama, soft studio lighting, subtle contact shadow, 50mm photography, ecommerce hero, clean negative space",1:1
mug-charcoal-01,"Product packshot: matte ceramic mug, charcoal glaze, seamless white cyclorama, soft studio lighting, subtle contact shadow, 50mm photography, ecommerce hero, clean negative space",1:1

Hinweise zum Produktivcode:

• ThreadPoolExecutor(max_workers=8) ist für schnell eine sichere Parallelität. Höher vertieft nur die Warteschlange, beschleunigt aber nichts.
• Der Timeout von 180 Sekunden pro Aufgabe ist konservativ gesetzt; tatsächlich schließt jede erfolgreiche Aufgabe in 30–60 Sekunden ab. Ein ausgelöster Timeout bedeutet, dass die Aufgabe hängt – die vier Ursachen findest du im hiapi-Leitfaden zu hängenden/timeoutenden Aufgaben.
• Wir laden direkt nach success herunter. output[].url ist ein temporärer Link mit einem expireAt-Zeitstempel; speichere ihn nicht in deinem CMS.

Prompt-Templates, die dir langweilige, aber nützliche Produktbilder liefern

Katalog-Prompts sind keine kreativen Prompts. Du willst jedes Mal dieselbe Beleuchtung, denselben Hintergrund, dieselbe Kamera – nur das Produkt ändert sich. Ein Template:

Product packshot: {MATERIAL} {PRODUCT}, {COLOR} {FINISH},
{COMPOSITION},
{BACKGROUND},
{LIGHTING},
{LENS_NOTE},
ecommerce hero, no props, clean negative space {AREA}

Ausgefüllt:

Product packshot: matte ceramic coffee mug, soft beige glaze,
centered single subject filling about 60% of frame,
seamless white cyclorama background,
soft diffused studio lighting from the upper left, subtle contact shadow underneath,
shot on 50mm with shallow depth of field,
ecommerce hero, no props, clean negative space top and bottom

Die Reihenfolge ist weniger wichtig als die Struktur. Folgendes verbessert die Ergebnisse kontinuierlich:

• „seamless white cyclorama“ ist besser als „white background“ – Ersteres deutet auf eine nahtlose Studio-Unendlichkeitskulisse hin, Letzteres liefert manchmal ein Tischtuch.
• „subtle contact shadow underneath“ verhindert, dass das Produkt schwebend wirkt.
• „filling about 60% of frame“ verankert die Komposition; ohne dies zoomt schnell manchmal weit heraus oder schiebt das Produkt in eine Ecke.
• „no props“ verhindert, dass neben der Tasse überflüssige Teller, Blätter oder Schreibwaren auftauchen.

Für Szenenvarianten ersetze den Hintergrund- + Beleuchtungsblock:

... matte ceramic coffee mug, soft beige glaze, single subject filling about 40% of frame,
on a light oak countertop with morning sunlight from a kitchen window,
soft golden-hour rim lighting, gentle defocused background showing a blurred linen curtain,
shot on 35mm at f/2.8, lifestyle photography, no people, no other props

Für Draufsicht-Flatlays:

... single subject centered, top-down 90-degree angle, ceramic coffee mug, soft beige glaze,
on a light grey paper surface, soft even overhead lighting, soft shadow directly under the rim,
shot on 50mm, flatlay product photography, no props, clean negative space all sides, 1:1

Wenn du diese drei Prompts für dieselbe SKU ausführst, erhältst du für $0.015 eine brauchbare Produktdetailseiten-Galerie.

Farb-/Materialvarianten ohne Neuaufnahme

Der Grund, warum schnell im E-Commerce glänzt, ist die Variantengenerierung. Sobald ein Prompt für eine Farbe funktioniert, kannst du die übrigen Farben per String-Ersetzung der Farbdeskriptoren in Serie produzieren:

COLORS = [
    ("beige", "soft beige glaze"),
    ("charcoal", "deep charcoal matte glaze"),
    ("sage", "muted sage green glaze"),
    ("terracotta", "warm terracotta clay glaze"),
    ("cream", "off-white cream glaze with subtle speckle"),
]

TEMPLATE = (
    "Product packshot: matte ceramic coffee mug, {color_desc}, "
    "centered single subject filling about 60% of frame, "
    "seamless white cyclorama background, soft diffused studio lighting from the upper left, "
    "subtle contact shadow underneath, shot on 50mm, ecommerce hero, no props, "
    "clean negative space top and bottom"
)

rows = [{"sku": f"mug-{c}-01", "prompt": TEMPLATE.format(color_desc=desc),
         "aspect_ratio": "1:1"} for c, desc in COLORS]

Fünf Varianten zu $0.005 = $0.025 für den gesamten Farbwähler. Der Haken: schnell hält die Form zwischen verschiedenen Renderings nicht perfekt. Griffdicke, Randkurve und Proportionen driften zwischen den Farben leicht. Für eine stilisierte Produktseite ist das in Ordnung. Für pixelgenau identische Varianten brauchst du Referenzbild-Konditionierung, also flux-1.1-pro mit Referenzbild oder nano-banana-pro statt schnell.

An dein Shop-Frontend anbinden

Die Ausgabe ist eine heruntergeladene JPG-Datei. Der Weg von dort zur Live-Produktdetailseite hängt von deiner Plattform ab:

• Shopify: POST /admin/api/2025-01/products/{id}/images.json mit dem Body {"image": {"attachment": "<base64>"}}. Gibt eine von Shopify gehostete CDN-URL zurück.
• WooCommerce: Über die WP-Mediathek hochladen (POST /wp-json/wp/v2/media) und dann das Produkt mit der zurückgegebenen Medien-ID per images: [{id: ...}] PATCHen.
• Headless / eigenes CMS: In deinen eigenen Objektspeicher hochladen (S3, R2, Cloudflare Images) und die generierte URL im Produktdatensatz referenzieren.

In jedem Fall serverseitig hochladen, nicht clientseitig, damit dein hiapi-Schlüssel niemals den Browser erreicht.

Kostenrechnung für die Planung

Bei $0.005 pro Bild ist das Budget selten die Einschränkung – aber in Batches zu denken hilft:

Batch	Bilder	Kosten
Eine SKU, 4 Bilder	4	$0.02
Launch mit 50 SKUs, je 4 Bilder	200	$1.00
Katalog-Auffrischung mit 200 SKUs	800	$4.00
Täglicher Variantentest, 100 Bilder pro Tag, 30 Tage lang	3,000	$15.00

Auf hiapi sind die tokenseitigen Kosten des Bild-Endpunkts (Prompts) kostenlos – du zahlst nur für die ausgegebenen Bilder.

Was flux-schnell nicht gut kann

Was du vor dem Start einplanen musst:

• Lesbarer Etikettentext. Wenn dein Produktbild ein klar lesbares Marken-Wortzeichen braucht, generiere zuerst das Basisbild mit schnell und montiere dann das echte Etikett als PNG im Bildeditor darüber. schnell zu bitten, „'OAK ROAST' auf der Tasse“ zu rendern, erzeugt in etwa 80 % der Fälle Kauderwelsch.
• Produkt in der Hand. Menschliche Anatomie ist eine Schwäche von schnell. Für Szenenbilder mit Personen verwende stattdessen nano-banana-pro oder flux-1.1-pro.
• Pixelgenau konsistente Produkte über Varianten hinweg. Verwende hierfür ein Modell, das Referenzbilder unterstützt.
• Submillimeter-Details (Schmuck, Uhren mit sichtbaren Zeigern, geätztes Metall). Das ist das Revier der Premium-Modelle.

Für alles andere auf der Produktdetailseite – Hintergründe, Beleuchtung, Farbvarianten, Kontextbilder, Stimmung – ist flux-schnell das richtige Werkzeug im richtigen Preissegment mit der richtigen Durchlaufzeit. Der gesamte Zyklus passt in ein while true: poll; download-Skript und eine SKU-CSV, und die Kosten sind so niedrig, dass du Prompts iterieren kannst, ohne eine Budgetbesprechung einzuberufen.

Häufige Fragen

F: Kann ich an flux-schnell ein Referenzbild senden? A: Nein. flux-schnell/text-to-image unterstützt ausschließlich Text-zu-Bild – das input-Feld akzeptiert nur prompt und aspect_ratio, mehr nicht. Für referenzkonditionierte Varianten verwende flux-1.1-pro oder nano-banana-pro, die beide auf hiapi Bildeingaben akzeptieren.

F: Welche Seitenverhältnisse werden unterstützt? A: 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 21:9 und auto. Jedes andere Verhältnis (z. B. 5:7, 2:1) wird beim Erstellen der Aufgabe abgelehnt, mit einem Fehler, der auf die unterstützte Menge verweist.

F: Warum gibt die Aufgabenerstellung einen 400 zurück, wenn ich resolution einbeziehe? A: Das input von flux-schnell akzeptiert nur aspect_ratio. Andere Bildmodelle auf hiapi (z. B. flux-2, nano-banana-pro) akzeptieren resolution (1K/2K/4K). Bei schnell entferne es.

F: Wie lange sind die Ausgabe-URLs gültig? A: Jede output[].url trägt einen expireAt-Zeitstempel (üblicherweise einige zehn Minuten). Sobald status auf success wechselt, lade die Bildbytes sofort herunter und speichere sie in deinem eigenen Bucket – verlinke die temporären URLs nicht hot in deiner Produktdatenbank.

F: Kann ich mehr als 8 Aufgaben gleichzeitig ausführen? A: Ja, aber es wird praktisch nicht schneller abgeschlossen – schnell ist Ende-zu-Ende bereits sehr schnell, und mehr als etwa 8 parallel stauen nur die Warteschlange. Für echte Massenabfertigung (Tausende) parallelisiere über mehrere Worker-Maschinen statt über Threads in einem Prozess.

F: Wie bekomme ich pixelgenau identische Varianten desselben Produkts? A: Mit schnell allein geht das nicht. Generiere zuerst einmal das Hauptbild und führe dann die Varianten mit einem Modell aus, das Referenzbilder unterstützt (flux-1.1-pro oder nano-banana-pro), wobei das Hauptbild als Referenz dient. Die Kosten steigen, aber die Formkonsistenz verbessert sich deutlich.