Comment utiliser bria-product-shot via l'API hiapi : curl, Python et une requête qui fonctionne

bria-product-shot reçoit une photo de produit et renvoie une nouvelle image qui place le produit dans une scène différente. Vous pouvez décrire la scène en anglais, ou fournir une image de référence pour qu'il suive le style d'arrière-plan de cette image. Ce guide présente une requête exécutée de bout en bout sur hiapi, ainsi que les règles de paramètres qui déterminent si une requête est acceptée.

Vous avez besoin d'une clé API hiapi, à obtenir depuis la page API Keys du tableau de bord, ainsi que d'une URL de photo de produit accessible publiquement (JPEG, PNG ou WEBP, 12 Mo maximum).

Exemple minimal fonctionnel (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"
    }
  }'

L'appel de création renvoie immédiatement un ID de tâche :

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

Interrogez GET /v1/tasks/<taskId> jusqu'à ce que data.status soit success ou fail. La réponse une fois terminée ressemble à ceci (le nom d'hôte de sortie est raccourci) :

{
  "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"
}

Version Python

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",
))

Paramètres clés

Champ	Description
image_url	Obligatoire. URL http(s) publique de la photo de produit.
prompt	Description de scène en anglais, de 1 à 1000 caractères.
reference_image_url	Image de référence de la scène. Utilisez ce paramètre ou prompt, l'un ou l'autre, jamais les deux à la fois.
placement_type	manual_placement (par défaut) place le produit à un emplacement prédéfini ; original conserve sa position dans la photo.
manual_placement_selection	bottom_center (par défaut), upper_left, upper_right, bottom_left, bottom_right, right_center, left_center, upper_center, center_vertical, center_horizontal. Valide uniquement avec manual_placement.
original_quality	Valide uniquement avec original : conserve les dimensions d'entrée au lieu de redimensionner à environ 1 MP.
fast	true par défaut. Désactivez-le pour utiliser le modèle standard ; le prix reste le même.
optimize_description	true par défaut. Enrichit le texte de la scène ; valide uniquement avec prompt, non utilisable avec une image de référence.

Ce schéma est fermé (additionalProperties: false) et comporte des règles inter-champs, de sorte que prompt plus reference_image_url, ou original plus un emplacement prédéfini, constituent des requêtes invalides.

Journal de test et remarques

Ce qui a été exécuté sur l'API en direct :

• Une génération réelle a été effectuée avec la requête ci-dessus, fast restant à sa valeur par défaut. La tâche est passée par handling et archiving, puis a atteint success environ 26 secondes après sa création.
• Pour une entrée carrée, la sortie est un PNG 1024×1024 (environ 1 Mo), ce qui correspond à l'indication de la page du modèle : pour une entrée carrée, les emplacements prédéfinis sont mesurés sur 1024×1024.
• Une valeur erronée intentionnelle "manual_placement_selection": "middle" a été rejetée à la création, avec un HTTP 400 et error_code: INVALID_REQUEST. Le message d'erreur énumère les dix emplacements autorisés, ce qui vous permet de l'afficher directement à l'utilisateur sans attendre l'échec de la tâche.

Conseils pratiques :

• Téléchargez la sortie immédiatement. Chaque sortie possède un horodatage expireAt (heure Unix après achèvement, environ sept jours) ; stockez l'image dans votre propre stockage.
• Tarification par image. Selon la page du modèle, le texte de scène et l'image de référence, l'emplacement et le mode rapide ne modifient pas le prix. Consultez les chiffres actuels sur la page de tarification plutôt que de les coder en dur.
• Ce guide n'a exécuté qu'une seule génération ; la page ne fait donc aucune déclaration sur la qualité selon les différentes catégories de produits. Testez d'abord vos propres images de catalogue avant une utilisation en masse.

Recommandations pour la production

• Créez la tâche, stockez le taskId et interrogez le statut en réessayant quelques fois en cas d'erreur réseau temporaire. Réinterrogez l'ID sauvegardé plutôt que de créer une nouvelle tâche, car une nouvelle tâche est facturée à nouveau.
• Pour les files d'attente, validez manual_placement_selection côté client parmi les dix valeurs ci-dessus, afin que les entrées erronées n'atteignent jamais l'API.

Pages connexes

• Page du modèle Bria Product Shot : tarification en direct, formulaire de saisie et aire de jeu.
• Page du modèle Bria Eraser : supprimez des objets à l'aide d'un masque, une tâche différente de l'insertion d'un produit dans une nouvelle scène.
• Parcourir tous les modèles d'image
• Guide de l'API de suppression d'arrière-plan 851-labs : si l'arrière-plan de votre photo source est encombré, détourez d'abord le produit.
• Comment utiliser l'API image vers image FLUX.2

Questions fréquentes

Puis-je utiliser une image de référence à la place d'un prompt textuel ? Oui. Envoyez reference_image_url et omettez prompt. N'envoyez pas les deux en même temps, et n'envoyez pas optimize_description avec une image de référence.

Combien d'images un appel renvoie-t-il ? Une seule. La page du modèle indique une image en sortie par exécution.

Le produit conservera-t-il sa position dans ma photo ? Seulement avec placement_type: "original". Le manual_placement par défaut le repositionne à l'emplacement prédéfini choisi.