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

Ein E-Commerce-Produktkatalog steht und fällt mit Konsistenz. Ein Verkäufer mit 40 SKUs braucht keine 40 verschiedenen Shootings – er braucht einen ansprechenden Hintergrund und eine Möglichkeit, jedes Produkt schnell davor zu platzieren. Genau das ist der echte Anwendungsfall für referenzbildgesteuerte Bildbearbeitung, und genau dafür ist grok-imagine/image-to-image auf der hiapi API gemacht: Man gibt ihm eine Szene und ein Produktfoto, und es fügt beides zu einem sauberen, markenkonformen Bild zusammen – ohne manuelle Maskierung und ohne separaten Freistellungsschritt.

Diese Anleitung behandelt das echte, getestete Request-Schema des Modells (kein Marketingtext), die tatsächlich abgerechnete Preisgestaltung, ein Batch-Skript, das denselben Hintergrund auf einen ganzen Produktkatalog anwendet, sowie einen praktischen Trick: die Steuerung des Ausgabeseitenverhältnisses über mehrere E-Commerce-Plattformen hinweg, die jeweils unterschiedliche Zuschnittformate verlangen.

Was das Modell tatsächlich tut

grok-imagine/image-to-image nimmt einen Text-Prompt und einige Referenzbilder entgegen und verschmilzt sie zu einem neuen Bild. Für die Produktfotografie bedeutet das:

• Vereinheitlichung des Hintergrunds – jedes SKU-Foto vor dieselbe stilisierte Szene stellen (ein Tisch, ein Regal, ein Studiohintergrundtuch), ohne irgendetwas neu zu fotografieren.
• Szenensynthese – ein Produktfreisteller wird mit einem Umgebungsreferenzbild kombiniert, sodass Licht und Komposition zusammenpassen.
• Stiltransfer zwischen Referenzbildern – Farbgebung oder Requisiten eines Bildes in ein anderes übertragen, während das Produkt selbst unverändert bleibt.

All das geschieht in einem einzigen Task-Aufruf, abgerechnet pro ausgegebenem Bild plus einer geringen Gebühr für jedes gesendete Referenzbild.

Das echte Schema (an der Live-API verifiziert, nicht auf der Preisseite)

Wir haben POST /v1/tasks direkt mit grok-imagine/image-to-image abgefragt; das Eingabeschema dieses Modells akzeptiert genau zwei Felder:

{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "string, required",
    "image_urls": ["array of public image URLs, required, max 3"]
  }
}

Das ist alles – kein resolution, kein aspect_ratio und kein strength-Parameter. Jeglicher andere Inhalt in der Payload wird vom strikten Schema abgelehnt.

Eine Korrektur, die es wert ist, erwähnt zu werden: Die hiapi-Preisseite behauptet derzeit, das Modell unterstütze „bis zu 6“ Referenzbilder. Wir haben 6 bzw. 7 Bild-URLs im selben Request gesendet und beide wurden abgelehnt:

{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 6, want 3"}
{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 7, want 3"}

Zum Zeitpunkt dieses Artikels liegt das tatsächlich durchgesetzte Limit bei 3 Bildern pro Aufruf, nicht 6. Wenn Sie eine Pipeline um dieses Modell herum bauen, planen Sie mit 3 und betrachten Sie jeglichen Marketingtext, der etwas anderes sagt, als veraltet – bestätigen Sie das Limit mit einem Live-POST /v1/tasks-Aufruf, bevor Sie eine Automatisierung ausliefern, die davon abhängt, denn solche Limits ändern sich mit der Weiterentwicklung der Plattform.

Automatisches Seitenverhältnis: Das Ausgabeformat folgt Ihrem ersten Referenzbild

Das Modell hat kein aspect_ratio-Eingabefeld – woher kommt also die Form der Ausgabe? Wir haben einen kontrollierten Test durchgeführt, um das herauszufinden: derselbe Prompt, dieselben zwei Referenzbilder, nur die Reihenfolge der image_urls vertauscht.

Bei diesem Rendering war das Produktfoto (der Rucksack) an erster Stelle in image_urls aufgeführt, gefolgt von der Hintergrundszene. Die Ausgabe kam als 1248×832 zurück – ein Querformatbild im Verhältnis 3:2, passend zum Seitenverhältnis des Produktfotos.

Derselbe Prompt, dieselben zwei Bilder – doch diesmal stand die Hintergrundszene an erster Stelle. Die Ausgabe kam als 1024×1024 zurück, ein quadratischer Zuschnitt, der dem Seitenverhältnis des Szenenreferenzbildes entspricht und nicht dem des Produkts.

Die Regel lautet: Das Ausgabeseitenverhältnis von grok-imagine/image-to-image übernimmt das Verhältnis der URL, die in image_urls an erster Stelle steht. Es liest keine Kompositionshinweise aus Ihrem Prompt („Produktfoto“ oder „breite Szene“) – es ist rein positional. Sobald man das weiß, ist es ein wirklich nützlicher Hebel: Um einen bestimmten Zuschnitt für eine E-Commerce-Plattform zu erzielen, muss man nur das Referenzbild-Array neu anordnen. Für quadratische Produktlisten im Instagram-Stil das quadratische Referenzbild nach vorne; für breite Bannerflächen das Querformat-Referenzbild nach vorne.

Preisgestaltung (gegen die Live-Preisliste geprüft)

Modell	Aufruftyp	Preis
grok-imagine/text-to-image	Text → Bild	$0,03 / Bild
grok-imagine/image-to-image	Referenzbildgesteuerte Bearbeitung (diese Anleitung)	$0,03 / Bild + $0,003 pro Referenzbild
grok-imagine-quality/text-to-image	Text → Bild, Premium-Stufe	$0,07 / Bild (1K)
grok-imagine-quality/image-to-image	Referenzbildgesteuerte Bearbeitung, Premium-Stufe	$0,08 / Bild (1K), $0,10 / Bild (2K), + $0,015 pro Referenzbild

Die in dieser Anleitung verwendete Basisstufe grok-imagine/image-to-image variiert nicht mit der Auflösung und hat einen Pauschalpreis – Sie zahlen keinen 2K/4K-Zuschlag wie bei der -quality-Stufe. Für Katalogaktualisierungen, bei denen Dutzende SKUs in dieselbe Szene eingefügt werden, sind $0,036 pro Bild (ein Produktfoto plus ein Szenenreferenzbild) die Zahl, mit der Sie kalkulieren sollten. Prüfen Sie vor umfangreichen Läufen immer erneut /en/pricing, da sich die Tarife ändern können.

Wenn Sie schärfere Details pro Bild benötigen und eine etwa dreifache Preissteigerung akzeptieren, ist die grok-imagine-quality-Stufe die hochauflösendere Version desselben Workflows. Für reine Text-zu-Bild-Produktrenders ganz ohne Referenzfoto lesen Sie die Anleitung zur Basisstufe Text-zu-Bild.

Batch-Skript: eine Szene, ein ganzer Katalog

Im Folgenden finden Sie eine minimale Python-Schleife, die eine wiederverwendbare Hintergrundszene entgegennimmt, sie mit jedem Produktfoto in einem Ordner zusammenfügt, jedes als eigenen Task einreicht und abfragt, bis es fertig ist. Sie verwendet das oben bestätigte Schema und platziert das Produktbild an erster Stelle, sodass jede Ausgabe das Seitenverhältnis des Produktfotos übernimmt – wenn Sie das Verhältnis der Szene möchten, tauschen Sie die Reihenfolge.

import os
import time
import requests

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

SCENE_URL = "https://static.hiapi.ai/blog/grok-imagine-image-to-image-ecommerce/scene-base.jpg"
PROMPT = (
    "Composite the product from the first reference photo naturally into the "
    "second reference's studio scene, matching its lighting and shadow direction. "
    "Keep the product's shape, color, and texture unchanged."
)


def submit(product_url: str) -> str:
    payload = {
        "model": "grok-imagine/image-to-image",
        "input": {
            "prompt": PROMPT,
            "image_urls": [product_url, SCENE_URL],  # product first -> output follows its ratio
        },
    }
    resp = requests.post(f"{API_BASE}/tasks", headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


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


if __name__ == "__main__":
    product_urls = [
        "https://your-storage.example.com/catalog/dripper-raw.jpg",
        "https://your-storage.example.com/catalog/sneaker-raw.jpg",
        "https://your-storage.example.com/catalog/backpack-raw.jpg",
    ]
    for url in product_urls:
        task_id = submit(url)
        output_url = wait_for_result(task_id)
        print(f"{url} -> {output_url}")

Für Produktions-Pipelines registrieren Sie eine callback.url am Task, anstatt in einer Schleife abzufragen – die vollständige Struktur der Callback-Payload finden Sie im hiapi-Modellkatalog. Speichern Sie die taskId zusammen mit Ihrer Produkt-SKU, damit fehlgeschlagene Tasks erneut versucht werden können, ohne den gesamten Batch erneut einzureichen.

Beispiele mit echten Produktfotos

Beide wurden mit demselben Hintergrundszenen-Referenzbild generiert, wobei zwischen den Aufrufen nur das Produktfoto ausgetauscht wurde – Licht, Tisch und Hintergrundpflanze bleiben im gesamten „Katalog“ konsistent, und genau darum geht es beim Workflow mit wiederverwendbaren Szenen.

Häufig gestellte Fragen

Kann man in einem Aufruf mehr als 3 Referenzbilder verwenden? Nein. Das Live-Schema erzwingt für image_urls maxItems: 3 – dies wurde durch direkte API-Tests bestätigt, unabhängig davon, was Marketingtexte anderswo behaupten. Gestalten Sie Ihre Prompts für höchstens 3 Referenzbilder (üblicherweise: Produkt + Szene oder Produkt + Szene + Stilreferenz).

Wie steuert man das Seitenverhältnis der Ausgabe? Das Modell hat keinen aspect_ratio-Parameter. Die Ausgabe übernimmt das Seitenverhältnis des ersten Bildes in image_urls – ordnen Sie Ihre Referenzbilder neu an, um das gewünschte Verhältnis zu erzielen.

Unterstützt es reine Textgenerierung ohne Referenzbild? Nein – image_urls ist ein Pflichtfeld. Für reine Text-Produktrenders verwenden Sie stattdessen grok-imagine/text-to-image zum Preis von $0,03/Bild.

Gibt es eine hochauflösendere Version des Modells? Ja, grok-imagine-quality/image-to-image führt denselben referenzbildgesteuerten Workflow für $0,08/Bild (1K) oder $0,10/Bild (2K) plus $0,015 pro Referenzbild aus und liefert schärfere Details.

Jetzt ausprobieren

Holen Sie sich einen API-Schlüssel von Ihrem hiapi-Dashboard, bereiten Sie eine Hintergrundszene vor und führen Sie Ihre ersten Tasks mit einigen wenigen SKUs aus, bevor Sie sich für einen vollständigen Katalogwechsel entscheiden – bei $0,036 pro Bild kostet das Testen dieses Workflows mit 10 Produkten weniger als einen Dollar.