gpt-image-2.5-flare für E-Commerce-Produktbilder: Batch-Workflows über die hiapi API

Produktfotografie ist meist der langsamste Teil der Katalogerstellung: Jede SKU braucht ein eigenes Studio-Shooting, jeder saisonale Hintergrund ein erneutes Shooting und jede Plattform mit anderen Seitenverhältnis-Vorgaben noch ein weiteres. gpt-image-2.5-flare auf hiapi bündelt den Großteil dieser Arbeit in einer einzigen Modell-ID – es erzeugt Produktbilder aus Text-Prompts und bearbeitet vorhandene Fotos (Hintergrund austauschen, in Lifestyle-Szenen einbetten, für verschiedene Kanäle skalieren), ohne das Produkt selbst zu verändern. Dieser Leitfaden zeigt drei echte Workflows mit unveränderten API-Ausgaben und erklärt anschließend, wie sich das Ganze auf den gesamten Produktkatalog anwenden lässt, statt Bild für Bild.

Die in den Abbildungen gezeigten Produkte (eine grüne Glasflasche mit der Aufschrift „MOSS“ und ein kobaltblauer Wasserkessel mit der Aufschrift „AER“) sind konzeptionelle Requisiten zur Demonstration dieser Technik, keine echte Kundenfotografie – aber jedes Bild ist eine echte, unbearbeitete Ausgabe der hiapi API, keine Simulation.

Warum eine einzige Modell-ID entscheidend ist

gpt-image-2.5-flare übernimmt zwei verschiedene Aufgaben, je nachdem, was man übergibt:

• image_urls weglassen, und es erzeugt ein Bild allein aus dem Text-Prompt (Text-zu-Bild).
• image_urls hinzufügen, und es bearbeitet stattdessen das übergebene Foto (Bild-zu-Bild) – dasselbe Modell, derselbe Endpunkt, dieselbe Preisgestaltung.

Für einen Produktkatalog ist das wichtiger, als es klingt: Ob man ein Produkt erstmals fotografiert oder ein vorhandenes Foto wiederverwendet, man muss nie zwischen zwei Modell-IDs oder zwei Preisplänen wechseln. Zwei weitere Details machen es besonders batchtauglich:

• Qualitätsstufen statt eines einzigen festen Preises. Pro Anfrage wählt man low / medium / high / xhigh / max, sodass ein Thumbnail-Batch über 500 SKUs und ein Dutzend Hero-Bilder für die Startseite nicht zum gleichen Stückpreis abgerechnet werden müssen.
• Flexible Seitenverhältnisse. Pro Anfrage sind 1:1, 4:5, 9:16, 16:9 und weitere Formate wählbar, sodass dasselbe Produktbild ohne erneutes Shooting auf ein quadratisches Marktplatz-Raster, einen vertikalen Mobile-Feed oder ein breites Banner zugeschnitten werden kann.

Jeder Aufruf läuft über die asynchrone Task-API von hiapi: POST /v1/tasks reicht den Auftrag ein, anschließend pollt man GET /v1/tasks/{id} (oder nutzt einen Callback), bis der Status success lautet. Es gibt keinen synchronen Aufruf, der das Bild direkt in der Antwort zurückliefert – Generierung und Bearbeitung dauern jeweils einige Sekunden.

Schritt 1: Eine saubere Studioaufnahme von Grund auf erzeugen

Man beginnt mit einem einfachen, gut ausgeleuchteten Studiofoto – das ist das Basismaterial, das in den folgenden Schritten bearbeitet wird.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_task(prompt, quality="medium", aspect_ratio="1:1", image_urls=None, idempotency_key=None):
    payload = {"model": "gpt-image-2.5-flare",
               "input": {"prompt": prompt, "quality": quality, "aspect_ratio": aspect_ratio}}
    if image_urls:
        payload["input"]["image_urls"] = image_urls
    headers = dict(HEADERS)
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    resp = requests.post(BASE, headers=headers, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id, timeout_s=300, poll_every=5):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]  # download or re-upload immediately — it expires
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


studio_shot_url = wait_for_task(create_task(
    "Photorealistic square studio product photograph. Center exactly one translucent forest-green "
    "glass perfume bottle with a brushed silver cylindrical cap on a pale ivory stone pedestal. A "
    "small rectangular cream label reads \"MOSS\" in a thin serif font. Soft diffused studio lighting, "
    "seamless pale warm-gray background, subtle reflection, no props, no text elsewhere in frame.",
    quality="medium",
    aspect_ratio="1:1",
))

quality="medium" ist ein sinnvoller Standard für den ersten Durchlauf – jedes Bild in diesem Artikel verwendet dieselbe Stufe. Nur wenn zusätzliche Details den Aufpreis wert sind, hebt man einzelne SKUs auf high an (siehe Preistabelle unten).

Schritt 2: Den Hintergrund neu gestalten, ohne das Produkt neu zu generieren

Hier liegt der Workflow, der wirklich Katalogarbeit spart: Man übergibt die Studioaufnahme als image_urls und beschreibt nur die gewünschte Änderung; das Produkt selbst bleibt pixelgenau identisch – gleiche Flaschenform, gleicher Verschluss, gleiches Etikett – während sich der Hintergrund ändert.

seasonal_variant_url = wait_for_task(create_task(
    "Edit the supplied product photograph. Change ONLY the seamless background from pale warm gray "
    "to muted terracotta orange. Preserve the exact bottle shape and green glass color, the silver "
    "cap, the cream label and all its text, the lighting direction, and the camera angle exactly.",
    quality="medium",
    aspect_ratio="1:1",
    image_urls=[studio_shot_url],
))

Dasselbe Muster funktioniert auch mit einem völlig anderen Produkt – hier ein kobaltblauer Wasserkessel, dessen Hintergrund durch einen warmen pfirsichfarbenen Studiohintergrund ersetzt wurde, auf dieselbe Weise erzeugt:

Das ist der Kern der Aufgabe „saisonaler Refresh“ oder „neues Marktplatz-Theme“: ein Bearbeitungsaufruf pro SKU, das Produkt bleibt unberührt, der Hintergrund ändert sich. Führt man das 500-mal aus, hat man den gesamten Katalog ohne erneutes Shooting neu thematisiert.

Schritt 3: Das Produkt in eine Lifestyle-Szene einbetten

Studioaufnahmen eignen sich für Marktplatz-Raster; Lifestyle-Szenen verkaufen das Produkt auf Landingpages oder in Anzeigen. Dasselbe Bearbeitungsmuster, ein größerer Prompt – das Modell platziert das exakte Produkt in eine plausible reale Umgebung, statt nur die Hintergrundfarbe zu ändern.

lifestyle_url = wait_for_task(create_task(
    "Create a photorealistic square lifestyle product photograph using the supplied blue kettle as "
    "the exact product reference. Keep the original cobalt-blue kettle, black handle and base, "
    "brushed-metal spout and lid, black knob, and all lettering completely unchanged. Place it on a "
    "sunlit kitchen countertop with soft natural morning light, a few blurred kitchen props in the "
    "background, shallow depth of field.",
    quality="medium",
    aspect_ratio="1:1",
    image_urls=["<your kettle product photo URL>"],
))

In jedem Bearbeitungs-Prompt die einschränkende Formulierung beibehalten („keep the original ... completely unchanged“) – genau sie hindert das Modell daran, das Produkt abdriften zu lassen, während alles andere verändert wird.

Batch-Automatisierung für den gesamten Produktkatalog

Ein einzelner Bearbeitungsaufruf ist nützlich; im Katalogmaßstab liegt der Wert darin, dasselbe Muster unbeaufsichtigt auf jede SKU anzuwenden. Bewährt hat sich in der Produktion folgende Struktur:

import concurrent.futures
import csv

QUALITY_BY_USE = {"thumbnail": "low", "listing": "medium", "hero": "high"}


def process_row(row):
    idem_key = f"{row['sku']}-{row['use']}-{row['background']}"
    prompt = (
        f"Edit the supplied product photograph. Change ONLY the seamless background to "
        f"{row['background']}. Preserve the exact product shape, color, materials, label text, "
        f"lighting direction, and camera angle."
    )
    try:
        task_id = create_task(
            prompt,
            quality=QUALITY_BY_USE[row["use"]],
            aspect_ratio=row["aspect_ratio"],
            image_urls=[row["source_photo_url"]],
            idempotency_key=idem_key,
        )
        return row["sku"], wait_for_task(task_id)
    except Exception as exc:
        return row["sku"], f"ERROR: {exc}"


with open("catalog.csv") as f:
    rows = list(csv.DictReader(f))  # sku,source_photo_url,background,use,aspect_ratio

with concurrent.futures.ThreadPoolExecutor(max_workers=4) as pool:
    results = list(pool.map(process_row, rows))

Bei mehr als einer Handvoll Bildern sind folgende Punkte wichtig:

• Idempotenzschlüssel pro Zeile. Für jede SKU/Variante einen eigenen Idempotency-Key-Header senden, damit eine nach einem Timeout erneut versuchte Anfrage keine doppelten – und doppelt abgerechneten – Tasks erzeugt.
• Parallelität begrenzen, nicht alles auf einmal abschicken. Ein kleiner Thread-Pool (oder ein asynchrones Semaphore) vermeidet das Auslösen von Rate-Limits; bei 429 mit Backoff erneut versuchen, statt es als harten Fehler zu behandeln.
• Die Qualitätsstufe am Bildzweck ausrichten, nicht einheitlich wählen: Thumbnails und Raster-Listings brauchen meist nur low/medium, während Hero-Bilder auf der Startseite oder Werbemotive high oder xhigh wert sind.
• Verschiedene Seitenverhältnisse von demselben bearbeiteten Ausgangsbild ableiten, nicht vom Original – zuerst einmal die Bearbeitung zum Hintergrundaustausch ausführen, dann von diesem Ergebnis 1:1-, 4:5- und 9:16-Zuschnitte anfordern, damit jeder Kanal exakt dieselbe Produktdarstellung zeigt.
• Die Ausgabe-URLs sofort herunterladen oder erneut hochladen. Task-Ausgaben laufen ab; eine temporäre URL niemals als dauerhafte Bildquelle verwenden.

Preise

gpt-image-2.5-flare wird pro Ausgabebild anhand der Qualitätsstufe abgerechnet – ob von Grund auf generiert oder bearbeitet, der Tarif ist gleich:

Qualität	Preis pro Bild
low	$0.0172
medium	$0.0672
high	$0.1829
xhigh	$0.3572
auto	$0.3572
max	$0.7143

Bei der Stufe medium kostet die Neugestaltung des Themes für einen Katalog mit 500 SKUs – ein Bearbeitungsaufruf zum Hintergrundaustausch pro Produkt – etwa $33.60. Die vollständige, aktuelle Tarifübersicht aller Modelle findet sich auf der Preisseite.

Häufige Fragen

Verändert die Bearbeitung versehentlich mein Produkt? Den Bearbeitungs-Prompt auf eine einzige Änderung beschränken („nur den Hintergrund ändern …“) und ausdrücklich auflisten, was unverändert bleiben muss (Form, Farbe, Etikettentext, Kamerawinkel). Die obigen Beispiele zeigen, dass das Produkt bei jeder Bearbeitung unverändert bleibt.

Kann dasselbe Modell sowohl generieren als auch bearbeiten? Ja – gpt-image-2.5-flare ist eine einzige Modell-ID. Mit image_urls wird ein vorhandenes Foto bearbeitet; ohne wird allein aus dem Prompt generiert.

Wie viele Quellbilder lassen sich in einem Bearbeitungsaufruf übergeben? Über image_urls bis zu 16, wobei die meisten Katalog-Bearbeitungen nur eines benötigen – das Foto, das neu gestaltet werden soll.

Wie vermeidet man doppelte Abrechnung bei Wiederholungen? Pro Anfrage einen eindeutigen Idempotency-Key-Header senden. Eine erneut versuchte Anfrage mit demselben Schlüssel gibt den ursprünglichen Task zurück, statt einen neuen zu erzeugen.

Weiterführende Literatur

Wer den ersten Aufruf einrichtet, sollte mit dem gpt-image-2.5-flare API-Guide beginnen, der ein minimales Arbeitsbeispiel und einen tieferen Einblick in den Lebenszyklus asynchroner Tasks bietet. Weitere Prompt-Muster jenseits der Produktfotografie finden sich unter GPT Image 2.5 Flare Prompts: Copy-and-paste-Rezepte mit echten Ausgaben. Vollständige Parameter und Schemata stehen auf der Modellseite, die allgemeinen API-Konventionen (Authentifizierung, Task-Polling, Callbacks) in der hiapi-Dokumentation.

Bereit, es am eigenen Katalog auszuprobieren? Den API-Schlüssel im hiapi-Dashboard abrufen und dann das Studioaufnahme-Beispiel oben mit dem ersten Produktfoto ausführen.