Produktbilder in exakten Größen über die API generieren: Seitenverhältnisse und E-Commerce-Plattformspezifikationen

Jeder Vertriebskanal verlangt andere Maße für deine Produktbilder: Amazon möchte große quadratische Bilder auf weißem Grund, Instagram möchte ein 4:5-Hochformat, Pinterest möchte 2:3-Pins, und der Hero-Bereich deines eigenen Shops braucht ein ultrabreites Bild. Dieser Leitfaden zeigt, wie du all diese Größen programmatisch mit der hiapi API generierst – mit gpt-image-2 und wan2.7-image – und wie du jedes Mal exakt die Zielpixelgröße triffst.

Voraussetzungen: ein hiapi-API-Schlüssel (erstellt im Dashboard) sowie curl oder Python. Die Gesamtkosten hängen vom gewählten Modell und der Auflösung ab – siehe Preise.

Wie Bildgrößen in der API tatsächlich funktionieren

Zuerst der verwirrendste Punkt: Die Bildmodelle auf hiapi akzeptieren keine Pixelmaße. Es gibt kein Feld size, width oder height. Wenn du versuchst, eines zu übergeben, sagt dir die API das ausdrücklich:

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'size' not allowed"
}

Stattdessen wird die Größe durch zwei Felder in input gesteuert:

• aspect_ratio – die Form des Bildformats, ausgewählt aus einer festen Liste pro Modell.
• resolution – die Ausgabestufe: "1K", "2K" oder "4K" (die lange Seite entspricht ungefähr 1024 / 2048 / 4096 Pixeln; die genaue Pixelzahl variiert je nach Verhältnis, also prüfe immer die Datei, die du erhältst).

Hier sind die Parameter, die die beiden Modelle in diesem Leitfaden tatsächlich akzeptieren (gegen die Live-API verifiziert):

	gpt-image-2	wan2.7-image/text-to-image
prompt	erforderlich	erforderlich
aspect_ratio	auto, 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 3:1, 1:3, 21:9, 9:21 – insgesamt 16 Werte	1:1, 16:9, 4:3, 21:9, 3:4, 9:16, 8:1, 1:8 – insgesamt 8 Werte
resolution	1K, 2K, 4K	1K, 2K, 4K
Zusätzliche Fähigkeiten	Bild-zu-Bild-Variante (gpt-image-2/image-to-image)	seed (Integer) zur Reproduzierbarkeit
Pixel-size / n	nicht akzeptiert	nicht akzeptiert

Der praktische Unterschied: gpt-image-2 deckt die für Social- und E-Commerce-Plattformformate benötigten Verhältnisse ab (4:5, 2:3, 5:4 gibt es nur bei gpt-image-2), während wan2.7-image 8:1/1:8 ultrabreite Bannerstreifen hinzufügt, die keine andere Verhältnisliste abdeckt – ideal für schmale Werbebanner – und die übliche Wahl für 4K-Studioaufnahmen ist.

Für exakte Größenkontrolle besteht das Rezept also aus zwei Schritten:

1. Generiere mit dem passenden Seitenverhältnis und wähle die kleinste Auflösungsstufe, deren lange Seite das Ziel erreicht oder überschreitet (danach verkleinern, niemals vergrößern).
2. Skaliere die zurückgegebene Datei lokal auf die exakten Zielpixel – eine Zeile Pillow-Code.

Spickzettel für E-Commerce-Plattformspezifikationen

Hier sind gängige öffentliche Anforderungen, zugeordnet zu den API-Parametern:

Kanal	Typisches Ziel	aspect_ratio	resolution	Modellhinweis
Amazon-Hauptbild	lange Seite ≥1000 Pixel (ab 1600 Pixeln wird Zoom aktiviert), quadratisch, rein weißer Hintergrund	1:1	2K	beide möglich
Shopify-Produktseite	empfohlen 2048×2048	1:1	2K	beide möglich
Instagram-Feed (Hochformat)	1080×1350	4:5	2K	nur gpt-image-2
Stories / Reels / TikTok	1080×1920	9:16	2K	beide möglich
Pinterest-Pin	1000×1500	2:3	2K	nur gpt-image-2
Etsy-Angebot	empfohlen 2700×2025	4:3	4K	beide möglich (4K-Stufe erforderlich)
Website-Hero-Banner	z. B. 2560 Pixel breit	21:9	4K	beide möglich
Schmaler Werbebanner	ultrabreit	8:1	2K/4K	nur wan2.7-image

(Plattformspezifikationen ändern sich; betrachte diese Pixelziele als gängige öffentliche Empfehlungen und prüfe sie anhand der aktuellen Dokumentation jeder Plattform.)

Minimales lauffähiges Beispiel (curl)

Alles läuft über den einheitlichen asynchronen Task-Endpunkt: mit POST /v1/tasks erstellen, mit GET /v1/tasks/<id> abfragen. Erstelle ein Amazon-artiges quadratisches Bild in der 2K-Stufe:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {
      "prompt": "Studio product photo of a stainless steel water bottle on a pure white background, centered, soft shadow, e-commerce catalog style",
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

Die Task-ID in der Antwort findest du unter data.taskId. Frage sie ab:

curl -s https://api.hiapi.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Frage so lange ab, bis data.status zu "success" wird (oder "fail", Details stehen unter data.error). Die Bild-URL findest du unter data.output[0].url. Diese URL läuft ab (das Ausgabeobjekt enthält expireAt), also lade sie sofort herunter und hoste sie erneut in deinem eigenen Speicher – niemals direkt in Produktangeboten hotlinken.

Produktionsskript: ein Produkt, alle Kanäle, exakte Pixel

Dieses Batch-Skript erstellt alle Tasks im Voraus (sie laufen parallel auf der Plattform), fragt sie einzeln ab, bis sie fertig sind, und skaliert dann mit Pillow auf die exakten Zielgrößen. ImageOps.fit erledigt Verkleinerung und etwaige minimale Zuschnitte in einem einzigen Aufruf.

import os
import time
from io import BytesIO

import requests
from PIL import Image, ImageOps

API = "https://api.hiapi.ai/v1"
HDRS = {
    "Authorization": f"Bearer {os.environ['HIAPI_KEY']}",
    "Content-Type": "application/json",
}

# Kanal -> Generierungsparameter + exakte Pixelziele
SPECS = {
    "amazon-main":    {"model": "gpt-image-2/text-to-image", "aspect_ratio": "1:1",  "resolution": "2K", "px": (1600, 1600)},
    "shopify":        {"model": "gpt-image-2/text-to-image", "aspect_ratio": "1:1",  "resolution": "2K", "px": (2048, 2048)},
    "instagram-feed": {"model": "gpt-image-2/text-to-image", "aspect_ratio": "4:5",  "resolution": "2K", "px": (1080, 1350)},
    "story-reel":     {"model": "gpt-image-2/text-to-image", "aspect_ratio": "9:16", "resolution": "2K", "px": (1080, 1920)},
    "pinterest-pin":  {"model": "gpt-image-2/text-to-image", "aspect_ratio": "2:3",  "resolution": "2K", "px": (1000, 1500)},
    "etsy-listing":   {"model": "wan2.7-image/text-to-image", "aspect_ratio": "4:3",  "resolution": "4K", "px": (2700, 2025)},
    "hero-banner":    {"model": "wan2.7-image/text-to-image", "aspect_ratio": "21:9", "resolution": "4K", "px": (2560, 1097)},
}

PROMPT = (
    "Studio product photo of a stainless steel water bottle on a pure white "
    "background, centered, soft shadow, high detail, e-commerce catalog style"
)


def create_task(model: str, prompt: str, aspect_ratio: str, resolution: str) -> str:
    body = {
        "model": model,
        "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "resolution": resolution},
    }
    data = requests.post(f"{API}/tasks", json=body, headers=HDRS, timeout=60).json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id


def wait_task(task_id: str, timeout_s: int = 600) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        data = requests.get(f"{API}/tasks/{task_id}", headers=HDRS, timeout=30).json()
        task = data.get("data") or {}
        if task.get("status") == "success":
            return task["output"][0]["url"]
        if task.get("status") == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task {task_id} failed: {err.get('code')} {err.get('message')}")
        time.sleep(5)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


def save_exact(url: str, px: tuple, path: str) -> None:
    # Ausgabe-URLs laufen ab – sofort herunterladen und dann auf exakte Pixel anpassen.
    raw = requests.get(url, timeout=120).content
    img = Image.open(BytesIO(raw))
    ImageOps.fit(img, px, Image.LANCZOS).save(path)


if __name__ == "__main__":
    # Zuerst alle Tasks erstellen: Tasks laufen auf der Plattform nebenläufig
    tasks = {
        name: create_task(s["model"], PROMPT, s["aspect_ratio"], s["resolution"])
        for name, s in SPECS.items()
    }
    for name, task_id in tasks.items():
        url = wait_task(task_id)
        save_exact(url, SPECS[name]["px"], f"{name}.png")
        print(f"{name}: {SPECS[name]['px']} -> {name}.png")

Auch wenn du den Rest umschreibst, lohnt es sich, zwei Details zu übernehmen:

• Wähle die Auflösungsstufe so, dass die lange Seite ≥ dem Ziel ist. Etsys Ziel von 2700 Pixeln übersteigt die rund 2048 Pixel der 2K-Stufe, also generiere mit 4K und verkleinere anschließend. Verkleinern mit LANCZOS ist für Katalogzwecke visuell verlustfrei; Vergrößern nicht.
• Persistiere die taskId sofort nach dem Erstellen des Tasks. Wenn dein Worker abstürzt, frage bei der Wiederaufnahme die gespeicherte ID ab, statt den Task neu zu erstellen – eine Neuerstellung erzeugt (und berechnet) ein zweites Bild.

Alternativ ein bereits freigegebenes Hauptbild neu layouten

Oft willst du nicht sieben unabhängig generierte Bilder – du willst dasselbe freigegebene Produktbild, für jeden Kanal neu komponiert. Genau dafür ist gpt-image-2/image-to-image da: Es benötigt input_urls (ein Array öffentlich erreichbarer Bild-URLs) sowie prompt und akzeptiert dieselben 16 aspect_ratio-Werte:

{
  "model": "gpt-image-2/image-to-image",
  "input": {
    "prompt": "Extend the background naturally to fill the new frame; keep the product unchanged and centered",
    "input_urls": ["https://your-cdn.com/hero-shot.png"],
    "aspect_ratio": "9:16"
  }
}

Gleicher Task-Lebenszyklus, und am Ende folgt derselbe Schritt für exakte Pixel. Eine vollständige Einführung findest du unter How to Use gpt-image-2 Image-to-Image via the hiapi API.

Hinweise für den Produktivbetrieb

Nutze Callbacks statt Polling. Für serverseitige Nutzung übergib beim Erstellen des Tasks ein callback auf oberster Ebene und überspringe die Polling-Schleife ganz:

{
  "model": "gpt-image-2/text-to-image",
  "input": {"prompt": "...", "aspect_ratio": "1:1", "resolution": "2K"},
  "callback": {"url": "https://yourapp.com/hooks/hiapi", "when": "final"}
}

Du erhältst dann einmalig einen POST beim finalen Status. Behandle den Callback als Signal und nicht als Wahrheitsquelle: Hole vor dem Handeln erneut GET /v1/tasks/<id> ab und dedupliziere nach taskId. Wenn der Callback gar nicht ankommt, siehe Why your hiapi task callback isn't firing.

Fehlerbehandlung. Bei Authentifizierungsfehlern wird 401 permission_denied zurückgegeben – prüfe zuerst den Header Authorization: Bearer sk-.... Bei Validierungsfehlern wird 400 mit error_code: "INVALID_REQUEST" zurückgegeben; die Meldung ist besonders hilfreich: Sie listet die genau erlaubten Werte auf (so wurde die obige Verhältnistabelle verifiziert). Das Eingabe-Schema unterscheidet sich je nach Modell – wan2.7-image akzeptiert seed, gpt-image-2 nicht; einige schnelle Modelle lehnen resolution gänzlich ab – sieh dir also die Seite jedes Modells an, bevor du Felder fest codierst.

Kostenkontrolle. Die Preise variieren je nach Modell und Auflösungsstufe. Verwende 1K beim Iterieren von Prompts und wechsle erst für die Endversion auf 2K/4K – die aktuellen Preise pro Bild findest du auf der Preisseite.

Weiterführende Lektüre

• gpt-image-2 Text-to-Image-Modellseite · wan2.7-image Text-to-Image-Modellseite
• How to use gpt-image-2/text-to-image via the hiapi API – vollständige Parameterübung
• Wan 2.7 Text-to-Image for E-Commerce Product Photos: 4K Studio Shots
• Best AI Image Generation APIs in 2026 – Modellvergleich, falls du noch am Auswählen bist

Häufige Fragen

Kann ich in der Anfrage exakte Pixelmaße wie 1080×1350 übergeben? Nein. size, width und height werden mit 400 abgelehnt (additional properties ... not allowed). Generiere mit dem passenden aspect_ratio und einer resolution-Stufe, die dem Ziel entspricht oder darüber liegt, und verkleinere dann lokal auf die exakten Pixel – also die Pillow-Zeile oben.

Welche Einstellungen sollte ich für Amazon-Hauptbilder verwenden? aspect_ratio: "1:1", resolution: "2K" und dann auf deine Zielgröße anpassen (1600×1600 ist ein solider Standard – über der Zoom-Schwelle von 1000 Pixeln). Amazon-Hauptbilder erfordern außerdem einen rein weißen Hintergrund, also schreibe das in den Prompt und prüfe die Ausgabe vor dem Einstellen.

Mein Zielverhältnis ist nicht in der Liste (z. B. das 1,91:1-Format für Link-Anzeigen). Was tun? Generiere mit dem nächstgelegenen breiteren oder gleichen Verhältnis, das das Ziel vollständig abdeckt – für 1,91:1 etwa 2:1 oder 16:9 – und schneide dann mittig zu. Genau das macht ImageOps.fit im Skript: Zuschnitt des Überstands und Größenanpassung in einem Aufruf.

Wie erhalte ich echte 4K-Produktbilder? Setze bei beiden Modellen resolution: "4K". wan2.7-image ist die übliche Wahl für 4K-Studioaufnahmen; Prompt-Muster findest du im Wan 2.7 E-Commerce-Leitfaden.

Laufen generierte Bild-URLs ab? Ja – jede Ausgabe enthält expireAt. Lade die Datei sofort nach erfolgreichem Task herunter und hoste sie erneut in deinem eigenen Speicher. Klebe die Ausgabe-URL eines Tasks niemals in Produktangebote.

Kann ich mehrere Varianten in einer Anfrage generieren? Nein – diese Modelle haben keinen n-Parameter. Erstelle einen Task pro Bild; Tasks laufen nebenläufig, also ist die Stapelverarbeitung in einer Schleife (wie im obigen Skript) praktisch genauso schnell. Bei wan2.7-image kannst du den seed ändern, um kontrollierte Varianten desselben Prompts zu erhalten.