E-Commerce-Produktbilder mit grok-imagine/text-to-image über die hiapi API generieren

Die meisten Produktbild-Pipelines brechen zusammen, sobald folgende Anforderung auftritt: Aus einem Foto sollen drei verschiedene Formate entstehen – ein quadratisches Bild für das Katalograster, ein Hochformat-Ausschnitt für die mobile Produktdetailseite (PDP) und ein breites Bild für den Hero-Banner der Startseite. Ein neu zugeschnittenes Hero-Bild sieht selten in allen Seitenverhältnissen gut aus – entweder wird das Produkt abgeschnitten oder es entstehen unschöne Leerflächen. grok-imagine/text-to-image umgeht dieses Problem: Es generiert native Bilder direkt im gewünschten Seitenverhältnis, darunter zwei Breitformate, die speziell für solche Banner-Aufgaben entwickelt wurden (2:1 und 20:9), und das auf der hiapi API zu einem einheitlichen Preis von $0,03 pro Bild – unabhängig von der Auflösung.

Dieser Leitfaden beschreibt die tatsächliche Anfragestruktur, die Schema-Fallstricke, auf die wir beim Testen gestoßen sind, ein Batch-Generierungsskript, das eine komplette Shot-Liste für ein einzelnes Produkt-Briefing ausführt, sowie eine ehrliche Kostenkalkulation für Kataloggrößenordnung.

Preispositionierung

Verifiziert anhand der hiapi-Preisseite zum Zeitpunkt der Erstellung dieses Artikels:

Modell	Preis pro Bild	Auflösung	Seitenverhältnis-Steuerung
grok-imagine/text-to-image	einheitlich $0,03	1K oder 2K, gleicher Preis	13 Seitenverhältnisse, darunter 2:1, 20:9
grok-imagine-quality/text-to-image	$0,07 (1K) / $0,10 (2K)	Preisstaffelung nach Auflösung	gleiches Seitenverhältnis-Set

Die Qualitätsstufe bietet tatsächlich deutliche Verbesserungen bei feinen Details – Reflexionen, Gewebestrukturen, kleine Schrift –, und für eine kleine Anzahl echter Hero-Bilder lohnt sich der Aufpreis. Für den Großteil der Bilder im Katalog (Raster-Miniaturansichten, Lifestyle-Varianten, andere Blickwinkel) ist das Basismodell bereits nah genug heran, und der 2- bis 3-fache Preisunterschied lohnt sich im Batch-Betrieb nicht.

Eine tatsächlich funktionierende Anfrage

Alle Bilder auf dieser Seite stammen von demselben Endpunkt:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-image",
    "input": {
      "prompt": "matte ceramic pour-over coffee dripper on a pale oak table, soft morning window light from the left, small negative space top-right, no text, no logo, product photography",
      "aspect_ratio": "1:1",
      "resolution": "2k"
    }
  }'

Dies gibt eine taskId zurück; pollen Sie GET /v1/tasks/{taskId}, bis status den Wert success hat, und rufen Sie dann output[0].url ab und laden Sie das Bild herunter – die URL ist signiert und läuft ab, daher sollten Sie die Bytes sofort speichern, anstatt direkt auf sie zu verlinken.

Drei Schema-Details haben uns während des Testens gestolpert und sollten bekannt sein, bevor Sie selbst bauen:

• aspect_ratio ist eine strikte Aufzählung mit 13 Werten, kein Freitext.Senden Sie einen anderen Wert, erhalten Sie einen 400-Fehler mit der vollständigen Liste: 2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2. Die beiden für Banner benötigten Seitenverhältnisse sind 2:1 und 20:9 – die meisten Bildmodelle auf hiapi reichen nur bis 21:9 oder bieten gar keine Ultrawide-Option.
• resolution akzeptiert nur Kleinbuchstaben – verwenden Sie "2k", nicht "2K". Die Großschreibweise wird direkt abgelehnt und nicht stillschweigend umgewandelt.
• Das Eingabeschema ist strikt.Überflüssige oder falsch geschriebene Felder (zurückgebliebene negative_prompt, aus anderen Modellbeispielen kopierte style-Schlüssel) lassen die gesamte Anfrage fehlschlagen, statt ignoriert zu werden.

Prompts für katalogtauglich saubere Bilder schreiben

Der größte Hebel für konsistente Katalogergebnisse besteht darin, explizit zu sagen, was Sie nicht wollen. Für das oben gezeigte Hero-Bild auf weißem Hintergrund lautet der effektive Prompt:

"Matte Keramik-Pour-over-Kaffeefilter auf reinweißem, nahtlosem Hintergrund, Studio-Softbox-Beleuchtung, zentriert, kein Schattenverlauf außer einem weichen Kontaktschatten, kein Text, kein Wasserzeichen, keine Requisiten, E-Commerce-Produktfotografie, scharfer Fokus"

Für Lifestyle-Varianten für sekundäre PDP-Bilder oder E-Mail-Banner ersetzen Sie Hintergrund und Lichtstimmung, behalten aber dieselbe Disziplin „kein Text / kein Wasserzeichen / keine anderen Requisiten als die angegebenen" bei – genau das verhindert, dass grok-imagine unruhige Objekte oder unlesbare Beschriftungen auf das Produkt selbst setzt:

"Derselbe Keramik-Pour-over-Filter auf einer hölzernen Küchenarbeitsplatte, daneben eine dampfende Tasse, warmes Morgenlicht, geringe Schärfentiefe, gemütlicher, sanft unscharfer Wohnküchen-Hintergrund, kein Text, kein Logo"

Workflow für Ultrawide-Banner

Wenn die Anforderung ein Startseiten- oder Kategorie-Banner und keine Katalog-Miniaturansicht ist, sind 2:1 und 20:9 genau die beiden Seitenverhältnisse, die grok-imagine besonders empfehlenswert machen. Der Trick besteht darin, den Negativraum direkt im Prompt zu beschreiben, anstatt darauf zu hoffen, dass ein Zuschnitt zufällig passt – beschreiben Sie, wo im Bild sich das Produkt befindet und welche Bereiche leer bleiben sollen:

"Matte Keramik-Pour-over-Kaffeefilter im rechten Drittel des Bildes platziert, Outdoor-Licht zur Goldenen Stunde, großzügiger leerer Negativraum über die linken zwei Drittel des Bildes für überlagerten Titeltext, filmische breite Komposition, kein Text, kein Logo"

{
  "model": "grok-imagine/text-to-image",
  "input": {
    "prompt": "matte ceramic pour-over coffee dripper positioned in the right third of frame, golden-hour outdoor light, generous empty negative space across the left two-thirds of the image for headline text overlay, cinematic wide composition, no text, no logo",
    "aspect_ratio": "20:9",
    "resolution": "2k"
  }
}

Wenn Ihr CMS exakte Pixelmaße statt eines Seitenverhältnisses benötigt, generieren Sie im nächstgelegenen unterstützten Seitenverhältnis und schneiden Sie dann verlustfrei aus diesem Bild zu – die konkrete Füllberechnung finden Sie in unseren Notizen zur Umsetzung exakter Maße über die API.

Eine komplette Shot-Liste im Batch generieren

Ein einzelnes Produkt-Briefing benötigt in der Regel mehr als ein Bild. Das folgende Skript bildet das tatsächliche Skript nach, mit dem die vier Bilder dieser Seite erzeugt wurden – für jedes Bild wird ein Task eingereicht, bis zur Fertigstellung gepollt und dann auf der Festplatte gespeichert:

import os
import time
import requests

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

SHOTS = [
    {
        "name": "hero",
        "prompt": "matte ceramic pour-over coffee dripper on a pure white seamless "
                  "background, studio softbox lighting, centered, e-commerce product "
                  "photography, no text, no watermark",
        "aspect_ratio": "1:1",
    },
    {
        "name": "lifestyle",
        "prompt": "same ceramic pour-over dripper on a wooden kitchen counter next to "
                  "a steaming mug, warm morning light, shallow depth of field, no text",
        "aspect_ratio": "4:3",
    },
    {
        "name": "banner",
        "prompt": "ceramic pour-over dripper in the right third of frame, soft studio "
                  "light, empty negative space across the left two-thirds for headline "
                  "text, no text, no logo",
        "aspect_ratio": "2:1",
    },
]


def create_task(shot):
    payload = {
        "model": "grok-imagine/text-to-image",
        "input": {"prompt": shot["prompt"], "aspect_ratio": shot["aspect_ratio"], "resolution": "2k"},
    }
    resp = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id, poll_interval=5, timeout_s=300):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


for shot in SHOTS:
    task_id = create_task(shot)
    url = wait_for_result(task_id)
    image_bytes = requests.get(url, timeout=120).content
    with open(f"{shot['name']}.jpg", "wb") as f:
        f.write(image_bytes)
    print(f"{shot['name']}: saved {len(image_bytes)} bytes")

Wenn Sie einen vollständigen Batch über mehrere SKUs ausführen, reichen Sie alle drei Tasks zunächst ein und pollen Sie sie dann parallel (ein kleines asyncio- oder Thread-Pool-Konstrukt genügt) – jeder Task ist normalerweise innerhalb einer Minute fertig, und serielles Ausführen summiert nur unnötige Leerlaufzeit.

Kosten für einen echten Katalog-Lauf

Bei einem einheitlichen Preis von $0,03 pro Bild kostet das obige Drei-Bild-Set (Hero + Lifestyle + Banner) $0,09 pro SKU. Hochgerechnet:

• 50 SKUs × 3 Bilder = 150 Bilder → $4,50
• 500 SKUs × 3 Bilder = 1.500 Bilder → $45
• Wenn nur die 2K-Hero-Bilder auf grok-imagine-quality hochgestuft werden ($0,10 statt $0,03), ergibt sich für 500 SKUs insgesamt $80 – verglichen mit einem einzelnen traditionellen Produktshooting immer noch nur ein Bruchteil.

grok-imagine im Vergleich zum restlichen Produktportfolio

Wenn ein Bild in Bewegung versetzt werden soll – etwa als 6-sekündiger Produktclip für Social Ads statt als statischer Banner –, deckt dieselbe Produktreihe dies über grok-imagine-image-to-video ab, das eines dieser statischen Bilder als Startframe verwendet; diesen Workflow haben wir separat im Kurzvideo-Leitfaden beschrieben. Für Teams, die einen Vergleich mit der auf Nano-Banana basierenden Katalog-Pipeline anstellen wollen, ist unser Nano-Banana-E-Commerce-Leitfaden die nächstliegende Gegenüberstellung – gleiche Task-API-Struktur, unterschiedliche Modellstärken.

Häufig gestellte Fragen

Unterstützt grok-imagine/text-to-image Referenzbilder (i2i) und nicht nur Text-Prompts? Ja – aber das ist eine separate Modellvariante (grok-imagine/image-to-image) mit eigenem Eingabeschema. Dieser Leitfaden behandelt den reinen Text-zu-Bild-Pfad.

Warum gibt meine Anfrage einen 400-Fehler mit „additional properties" zurück? Das Eingabeschema ist strikt. Prüfen Sie sorgfältig, dass Sie nur prompt, aspect_ratio und optional resolution senden – keine zusätzlichen Felder aus anderen Modellbeispielen übernehmen.

Kann ich exakte Maße wie 1200×630 erhalten, statt aus der Aufzählung zu wählen? Generieren Sie im nächstgelegenen unterstützten Seitenverhältnis (16:9 kommt vielen Web-Banner-Formen nahe) und schneiden Sie anschließend verlustfrei zu – die konkrete Füllmethode finden Sie im oben verlinkten Leitfaden für exakte Maße.

Lohnt sich die Wartezeit für 2K-Auflösung gegenüber 1K? Bei diesem Modell kosten beide Auflösungen gleich viel, daher sollten Sie standardmäßig 2K verwenden – es sei denn, Sie haben ein striktes Latenzbudget –, um mehr Details kostenlos zu erhalten.

Selbst ausprobieren

Der gesamte API-Zugriff hier ist mit einem Standard-hiapi-Schlüssel möglich – siehe die Dokumentation für Authentifizierung und die vollständige Referenz zum Task-Polling, und prüfen Sie vor einer verbindlichen Batch-Ausführung die Preisseite auf die aktuellen Tarife für das gesamte Modellportfolio.