Genera immagini di prodotti e-commerce con seedream-4.5/image-to-image tramite l'API hiapi

Un catalogo prodotti non è una singola foto, ma lo stesso SKU presentato in una dozzina di contesti: foto su fondo bianco, immagini in ambiente reale, ritocchi dopo il cambio di un componente da parte del fornitore e versioni abbinate allo sfondo del brand della stagione. Rifotografare o rigenerare da zero ogni volta compromette la coerenza, perché prompt completamente nuovi producono prodotti leggermente diversi.

seedream-4.5/image-to-image nasce proprio per questo. Riceve le tue foto reali del prodotto — o più immagini di riferimento contemporaneamente — insieme a un'istruzione di modifica in linguaggio naturale, e restituisce un'immagine modificata che preserva la geometria, i materiali e l'identità del brand del prodotto reale, cambiando solo ciò che richiedi: lo sfondo, i dettagli di usura o la correzione cromatica necessaria per allinearsi a un'identità visiva coerente. Su hiapi funziona, come tutti gli altri modelli, tramite lo stesso endpoint asincrono /v1/tasks, a $0,045 per immagine.

I due esempi seguenti sono chiamate API reali, con i prompt esatti e le immagini generate.

Perché modificare invece di rigenerare

Il testo-a-immagine e l'immagine-a-immagine risolvono problemi diversi:

• Testo-a-immagine crea prodotti dal nulla in base a una descrizione. Adatto al design concettuale, non al catalogo prodotti: chiedendo due volte ottieni due tazze diverse.
• Modifica immagine-a-immagine parte dalla tua foto reale del prodotto. Il modello tratta l'immagine di riferimento come verità di base per forma, proporzioni e identità del brand, cambiando solo ciò che il prompt specifica. È proprio questo che lo rende sicuro per le schede prodotto reali: il prodotto nell'output è ancora il tuo prodotto.

Il flusso di lavoro concreto è: conserva per ogni SKU una foto base pulita (basta una normale foto da studio come riferimento), poi esegui seedream-4.5/image-to-image una volta per ogni contesto che ti serve — scena in ambiente reale, sostituzione dello sfondo, sfondo coerente con il brand, ritocco dei dettagli — invece di rifotografare o ripromptare da zero ogni volta.

Esempio 1: sostituzione dello sfondo con una scena in ambiente reale

Riferimento base: una normale foto da studio di un dripper in ceramica su fondo bianco.

Prompt di modifica inviato al modello:

Keep the ceramic pour-over dripper's exact shape, glaze color, and proportions
unchanged. Place it on a warm wood kitchen counter next to a steaming ceramic
mug and an open burlap coffee bag. Warm golden-hour side lighting, shallow
depth of field, soft shadows. Do not alter the dripper itself in any way —
only change the surrounding scene.

Il risultato preserva il profilo e la smaltatura del dripper, riconoscibili a livello di pixel, e al contempo lo colloca in una scena di vita reale che una normale foto di prodotto non potrebbe produrre da sola: senza rifotografare e senza un passaggio di compositing separato.

Esempio 2: uniformare i prodotti su uno sfondo del brand

Riferimento base: una normale foto da studio di una sneaker in tela bianca.

Prompt di modifica inviato al modello:

Keep the sneaker's stitching, eyelets, laces, and canvas texture exactly as
shown. Replace the background with a solid terracotta studio backdrop and
place the sneaker on a matching terracotta pedestal. Even, soft studio
lighting from the upper left, subtle contact shadow. Do not change the
sneaker's shape, color, or any printed details.

Questo è il pattern per uniformare visivamente un catalogo: scegli un unico trattamento dello sfondo, poi fai passare la foto base di ogni SKU attraverso la stessa istruzione di modifica. I prodotti variano; lo sfondo, la direzione della luce e la tonalità restano coerenti, perché a controllarli è il prompt — non il prodotto stesso.

Chiamare direttamente l'API

seedream-4.5/image-to-image funziona tramite l'endpoint dei task asincroni di hiapi. Invia il task, esegui il polling finché non è completato, poi scarica il risultato.

curl:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4.5/image-to-image",
    "input": {
      "prompt": "Keep the product exactly as shown. Replace the background with a solid terracotta studio backdrop and matching pedestal. Even soft studio lighting from the upper left.",
      "image_urls": ["https://your-storage.example.com/base-product-photo.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

La risposta restituisce un task_id. Esegui il polling su GET /v1/tasks/{task_id} finché status non è succeeded, poi leggi l'URL dell'immagine da output[0].url. L'URL ha una scadenza: scarica subito.

Python (invio task + polling + download):

import os
import time
import requests

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


def edit_product_image(prompt: str, image_urls: list[str],
                        aspect_ratio: str = "1:1", resolution: str = "2K") -> bytes:
    resp = requests.post(
        f"{API_BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "seedream-4.5/image-to-image",
            "input": {
                "prompt": prompt,
                "image_urls": image_urls,
                "aspect_ratio": aspect_ratio,
                "resolution": resolution,
            },
        },
        timeout=30,
    )
    resp.raise_for_status()
    task_id = resp.json()["task_id"]

    while True:
        poll = requests.get(f"{API_BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        poll.raise_for_status()
        data = poll.json()
        if data["status"] == "succeeded":
            image_url = data["output"][0]["url"]
            return requests.get(image_url, timeout=30).content
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data.get('error')}")
        time.sleep(3)

Modifica in batch di un catalogo prodotti

Il pattern visto sopra si generalizza direttamente a un catalogo prodotti: mantieni una lista di (sku, base_photo_url), applica la stessa istruzione di modifica a ogni voce — o una variante specifica per ogni SKU — e salva i risultati con lo SKU come chiave.

CATALOG = [
    {"sku": "dripper-ceramic-01", "base_url": "https://your-storage.example.com/dripper-01.jpg"},
    {"sku": "sneaker-canvas-white", "base_url": "https://your-storage.example.com/sneaker-white.jpg"},
    {"sku": "mug-stoneware-02", "base_url": "https://your-storage.example.com/mug-02.jpg"},
]

BACKDROP_PROMPT = (
    "Keep the product's exact shape, materials, and any printed branding "
    "unchanged. Replace the background with a solid terracotta studio "
    "backdrop and matching pedestal. Even soft studio lighting from the "
    "upper left, subtle contact shadow. Do not alter the product itself."
)

for item in CATALOG:
    image_bytes = edit_product_image(
        prompt=BACKDROP_PROMPT,
        image_urls=[item["base_url"]],
        aspect_ratio="1:1",
        resolution="2K",
    )
    with open(f"{item['sku']}-branded.jpg", "wb") as f:
        f.write(image_bytes)
    print(f"{item['sku']}: done")

A $0,045 per immagine, un trattamento dello sfondo su un catalogo di 50 SKU costa circa $2,25 — e poiché ogni task è indipendente, puoi parallelizzarlo tramite un pool di thread o una coda di task invece di eseguirlo in sequenza.

image_urls accetta fino a 14 immagini di riferimento per singola chiamata, quindi le varianti più avanzate possono fornire al modello più angolazioni dello stesso prodotto (frontale, laterale, dettaglio) in un'unica richiesta, quando una sola immagine di riferimento non basta per una modifica complessa.

Domande frequenti

seedream-4.5/image-to-image modifica il prodotto stesso o solo la scena? Segue scrupolosamente l'istruzione di modifica. Se il prompt descrive solo cambi di sfondo, luce o contesto e richiede esplicitamente di preservare il prodotto, la forma, il colore e i dettagli stampati del prodotto restano coerenti tra le varie modifiche — ed è proprio questo che lo rende utilizzabile per cataloghi di prodotti reali anziché per immagini concettuali una tantum.

Quante immagini di riferimento si possono inviare per singola chiamata? Fino a 14 URL di immagini pubblici in image_urls. La maggior parte delle modifiche a un singolo prodotto richiede una sola immagine (la foto base); più immagini di riferimento sono utili quando vuoi che il modello armonizzi i dettagli dello stesso oggetto da più angolazioni.

Quali risoluzioni sono supportate? resolution accetta 2K o 4K. Questo modello non ha un livello 1K.

Quanto costa modificare in batch un intero catalogo? $0,045 per immagine, indipendentemente dal livello di risoluzione. Un catalogo di 100 SKU con una modifica costa circa $4,50.

Si possono eseguire le modifiche in parallelo per velocizzare i task batch? Sì — ogni task è indipendente, quindi inviare più chiamate /v1/tasks in contemporanea (nel rispetto dei limiti di frequenza del tuo account) ed eseguirne il polling in parallelo è il modo più rapido per gestire cataloghi di grandi dimensioni.

Provalo in prima persona

Per il riferimento completo dei parametri e i prezzi in tempo reale, consulta la pagina del modello e la pagina dei prezzi. Per il formato esatto di richiesta/risposta dell'endpoint dei task citato sopra, vedi la documentazione sulla creazione dei task. Se stai impostando un flusso di lavoro simile con un livello di modello diverso, la guida e-commerce a seedream-5.0-lite approfondisce il pattern di ancoraggio al singolo SKU seguito da modifica.

Ottieni una chiave API ed esegui la tua prima modifica su una foto reale di prodotto — il codice qui sopra è pronto da copiare e incollare ed eseguire oggi sull'API hiapi.