So verwenden Sie bria-product-shot über die hiapi-API: curl, Python und eine funktionierende Anfrage

bria-product-shot nimmt ein Produktfoto entgegen und gibt ein neues Bild zurück, das das Produkt in einer anderen Umgebung platziert. Sie können die Szene auf Englisch beschreiben oder ein Referenzbild angeben, dessen Hintergrundstil das Modell übernehmen soll. Diese Anleitung zeigt eine Anfrage, die auf hiapi durchgängig ausgeführt wurde, sowie die Parameterregeln, die darüber entscheiden, ob eine Anfrage akzeptiert wird.

Sie benötigen einen hiapi-API-Schlüssel von der API-Keys-Seite im Dashboard sowie eine öffentlich zugängliche URL eines Produktfotos (JPEG, PNG oder WEBP, maximal 12 MB).

Minimales funktionierendes Beispiel (curl)

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bria-product-shot",
    "input": {
      "image_url": "https://your-cdn.example.com/serum-bottle.png",
      "prompt": "On a white marble countertop beside a window, soft morning light, a few green leaves in the background",
      "placement_type": "manual_placement",
      "manual_placement_selection": "bottom_center"
    }
  }'

Der Erstellungsaufruf gibt sofort eine Task-ID zurück:

{"code":200,"data":{"taskId":"tk-hiapi-01M5K7TWWMM68ZDTERJN4QV8MW"},"message":"success"}

Fragen Sie GET /v1/tasks/<taskId> ab, bis data.status success oder fail lautet. Die abgeschlossene Antwort sieht wie folgt aus (der Ausgabe-Hostname ist gekürzt):

{
  "code": 200,
  "data": {
    "model": "bria-product-shot",
    "status": "success",
    "storage": "temp",
    "taskId": "tk-hiapi-01M5K7TWWMM68ZDTERJN4QV8MW",
    "output": [{"artifactId": "287064", "type": "image", "expireAt": 1793325686,
                "url": "https://temp.hiapi.ai/.../...-0.png"}]
  },
  "message": "success"
}

Python-Version

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def product_shot(image_url: str, scene: str, position: str = "bottom_center") -> bytes:
    r = requests.post(API, headers=HEADERS, json={
        "model": "bria-product-shot",
        "input": {
            "image_url": image_url,
            "prompt": scene,
            "placement_type": "manual_placement",
            "manual_placement_selection": position,
        },
    }, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    for _ in range(60):
        d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if d["status"] == "success":
            # output URLs expire (about 7 days): download immediately
            return requests.get(d["output"][0]["url"], timeout=60).content
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(4)
    raise TimeoutError(task_id)

open("shot.png", "wb").write(product_shot(
    "https://your-cdn.example.com/serum-bottle.png",
    "On a white marble countertop beside a window, soft morning light, a few green leaves in the background",
))

Wichtige Parameter

Feld	Beschreibung
image_url	Erforderlich. Öffentliche http(s)-URL des Produktfotos.
prompt	Englische Szenenbeschreibung, 1–1000 Zeichen.
reference_image_url	Referenzbild für die Szene. Verwenden Sie diesen Parameter oder prompt, nur eines von beiden, niemals beide gleichzeitig.
placement_type	manual_placement (Standard) platziert das Produkt an einer vordefinierten Position; original behält dessen Position im Foto bei.
manual_placement_selection	bottom_center (Standard), upper_left, upper_right, bottom_left, bottom_right, right_center, left_center, upper_center, center_vertical, center_horizontal. Nur gültig bei Verwendung von manual_placement.
original_quality	Nur gültig bei Verwendung von original: behält die Eingabegröße bei, statt auf etwa 1 MP zu skalieren.
fast	Standard true. Deaktivieren, um das Standardmodell zu verwenden; Preis bleibt gleich.
optimize_description	Standard true. Erweitert den Szenentext; nur gültig bei Verwendung von prompt, nicht zusammen mit einem Referenzbild.

Das Schema ist geschlossen (additionalProperties: false) und enthält übergreifende Feldregeln, daher sind Kombinationen wie prompt plus reference_image_url oder original plus vordefinierte Position ungültige Anfragen.

Testprotokoll und Hinweise

Was gegen die Live-API ausgeführt wurde:

• Mit der obigen Anfrage wurde eine echte Generierung durchgeführt, wobei fast auf dem Standardwert blieb. Der Task durchlief handling und archiving und erreichte etwa 26 Sekunden nach der Erstellung success.
• Für quadratische Eingaben war die Ausgabe ein PNG mit 1024×1024 (etwa 1 MB), was mit der Beschreibung auf der Modellseite übereinstimmt: Bei quadratischen Eingaben werden vordefinierte Positionen anhand von 1024×1024 gemessen.
• Ein absichtlich falscher Wert "manual_placement_selection": "middle" wurde bei der Erstellung abgelehnt, mit HTTP 400 und error_code: INVALID_REQUEST. Die Fehlermeldung listet alle zehn erlaubten Positionen auf, sodass Sie sie direkt dem Benutzer anzeigen können, ohne auf einen fehlgeschlagenen Task warten zu müssen.

Praktische Tipps:

• Laden Sie die Ausgabe sofort herunter. Jede Ausgabe trägt einen expireAt-Zeitstempel (Unix-Zeit nach Abschluss, etwa sieben Tage); speichern Sie das Bild in Ihrem eigenen Speicher.
• Preis pro Bild. Laut Modellseite ändern Szenentext und Referenzbild, Platzierungsposition und Schnellmodus den Preis nicht. Prüfen Sie die aktuellen Zahlen auf der Preisseite, statt diese fest zu codieren.
• Diese Anleitung hat nur eine Generierung ausgeführt, daher macht die Seite keine Aussagen zur Qualität bei verschiedenen Produktkategorien. Testen Sie vor der Batch-Nutzung Ihre eigenen Katalogbilder.

Empfehlungen für die Produktion

• Erstellen Sie den Task, speichern Sie die taskId und wiederholen Sie die Abfrage bei vorübergehenden Netzwerkfehlern einige Male. Fragen Sie die gespeicherte ID erneut ab, statt einen neuen Task zu erstellen, da ein neuer Task erneut abgerechnet wird.
• Validieren Sie für Warteschlangen manual_placement_selection clientseitig anhand der oben genannten zehn Werte, damit fehlerhafte Eingaben niemals die API erreichen.

Verwandte Seiten

• Bria Product Shot – Modellseite: Live-Preise, Eingabeformular und Playground.
• Bria Eraser – Modellseite: Objekte mithilfe einer Maske entfernen – eine andere Aufgabe als das Platzieren eines Produkts in einer neuen Szene.
• Alle Bildmodelle durchsuchen
• 851-labs Hintergrundentferner-API-Anleitung: Wenn der Hintergrund Ihres Quellfotos unruhig ist, schneiden Sie das Produkt zuerst aus.
• So verwenden Sie die FLUX.2 Image-to-Image-API

Häufige Fragen

Kann ich ein Referenzbild anstelle eines Text-Prompts verwenden? Ja. Senden Sie reference_image_url und lassen Sie prompt weg. Senden Sie nicht beides gleichzeitig und senden Sie optimize_description nicht zusammen mit einem Referenzbild.

Wie viele Bilder werden pro Aufruf zurückgegeben? Eines. Die Modellseite gibt an, dass pro Lauf ein Bild ausgegeben wird.

Bleibt das Produkt an seiner Position in meinem Foto? Nur bei placement_type: "original". Das standardmäßige manual_placement positioniert es an der ausgewählten vordefinierten Position neu.