Come usare bria-product-shot tramite l'API hiapi: curl, Python e una richiesta funzionante

bria-product-shot riceve una foto di prodotto e restituisce una nuova immagine che colloca il prodotto in scene diverse. Puoi descrivere la scena in inglese oppure fornire un'immagine di riferimento per fargli seguire lo stile di sfondo di quell'immagine. Questa guida mostra una richiesta eseguita end-to-end su hiapi e le regole dei parametri che determinano se la richiesta viene accettata.

Devi ottenere una chiave API hiapi dalla pagina API Keys della dashboard e un URL di una foto di prodotto accessibile pubblicamente (JPEG, PNG o WEBP, massimo 12 MB).

Esempio minimo funzionante (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"
    }
  }'

La chiamata di creazione restituisce immediatamente un ID attività:

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

Esegui il polling di GET /v1/tasks/<taskId> finché data.status non è success o fail. La risposta al completamento è simile a questa (il nome host dell'output è abbreviato):

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

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

Parametri chiave

Campo	Descrizione
image_url	Obbligatorio. URL http(s) pubblico della foto di prodotto.
prompt	Descrizione della scena in inglese, da 1 a 1000 caratteri.
reference_image_url	Immagine di riferimento per la scena. Usa questo parametro oppure prompt, solo uno dei due, mai entrambi insieme.
placement_type	manual_placement (predefinito) colloca il prodotto in una posizione predefinita; original ne mantiene la posizione nella foto.
manual_placement_selection	bottom_center (predefinito), upper_left, upper_right, bottom_left, bottom_right, right_center, left_center, upper_center, center_vertical, center_horizontal. Valido solo quando si usa manual_placement.
original_quality	Valido solo quando si usa original: mantiene le dimensioni di input invece di ridimensionare a circa 1 MP.
fast	Predefinito true. Disattivalo per usare il modello standard; il prezzo è lo stesso.
optimize_description	Predefinito true. Espande il testo della scena; valido solo quando si usa prompt, non utilizzabile con un'immagine di riferimento.

Lo schema è chiuso (additionalProperties: false) e presenta regole tra campi, quindi combinazioni come prompt più reference_image_url, oppure original più una posizione predefinita, sono richieste non valide.

Record di test e note

Eseguito contro l'API live:

• Una generazione reale è stata eseguita con la richiesta sopra, mantenendo fast al valore predefinito. L'attività è passata per handling e archiving, raggiungendo success circa 26 secondi dopo la creazione.
• Per un input quadrato, l'output è un PNG 1024×1024 (circa 1 MB), in linea con quanto indicato nella pagina del modello: per input quadrati, le posizioni predefinite sono misurate su 1024×1024.
• Un valore errato inserito di proposito, "manual_placement_selection": "middle", è stato rifiutato al momento della creazione, restituendo HTTP 400 e error_code: INVALID_REQUEST. Il messaggio di errore elenca tutte e dieci le posizioni consentite, quindi puoi mostrarlo direttamente all'utente senza attendere il fallimento dell'attività.

Suggerimenti pratici:

• Scarica subito l'output. Ogni output ha un timestamp expireAt (ora Unix al completamento, circa sette giorni); salva l'immagine nel tuo storage.
• Prezzo fisso per immagine. Secondo la pagina del modello, il testo della scena, l'immagine di riferimento, la posizione e la modalità fast non modificano il prezzo. Controlla i valori attuali sulla pagina dei prezzi invece di codificarli a priori.
• Questa guida ha eseguito una sola generazione, quindi la pagina non formula alcuna dichiarazione sulla qualità per diverse categorie di prodotto. Prima di un uso massivo, testa le immagini del tuo catalogo.

Consigli per la produzione

• Crea l'attività, salva il taskId e, in caso di errori di rete temporanei, riprova il polling alcune volte. Esegui nuovamente il polling dell'ID salvato invece di creare una nuova attività, perché una nuova attività viene addebitata di nuovo.
• Per le code, valida manual_placement_selection lato client in base ai dieci valori sopra, così gli input errati non raggiungono mai l'API.

Pagine correlate

• Pagina del modello Bria Product Shot: prezzi in tempo reale, modulo di input e playground.
• Pagina del modello Bria Eraser: rimuove oggetti tramite maschera, un'attività diversa dal collocare un prodotto in una nuova scena.
• Sfoglia tutti i modelli di immagini
• Guida all'API di rimozione sfondo di 851-labs: se lo sfondo della foto di origine è disordinato, ritaglia prima il prodotto.
• Come usare l'API image-to-image di FLUX.2

Domande frequenti

Posso usare un'immagine di riferimento al posto del prompt testuale? Sì. Invia reference_image_url e ometti prompt. Non inviare entrambi e non inviare optimize_description insieme a un'immagine di riferimento.

Quante immagini restituisce una chiamata? Una. La pagina del modello indica che ogni esecuzione produce un'immagine.

Il prodotto manterrà la posizione nella mia foto? Solo con placement_type: "original". Il valore predefinito manual_placement lo riposiziona nella posizione predefinita selezionata.