API rimozione sfondo: consegnare PNG di prodotto trasparenti

Hai qualche centinaio di foto di prodotto scattate su tavoli grigi e davanzali, e il negozio, il marketplace o la designer vuole ciascuna come PNG trasparente. SpicyAPI Background Remover lo fa con una sola chiamata: invii l'URL di una foto e ricevi il soggetto principale su un PNG trasparente con la larghezza e l'altezza originali. Il lavoro che resta è tuo: confermare che il file abbia davvero l'alfa, controllare i bordi sugli sfondi su cui verrà usato ed esportare le copie appiattite che ogni destinazione richiede.

Prova prima nel Playground

Apri il Playground di background-remover-v1. Trascina una foto di prodotto in Input image, controlla il prezzo e premi Run model. Ispeziona il risultato trasparente su sfondi chiari e scuri prima di usare la stessa foto nel codice.

Cosa accetta e cosa restituisce l'endpoint

L'output mantiene le dimensioni del canvas di origine, quindi puoi posizionare il ritaglio su uno sfondo sostitutivo senza ridimensionare. Usa il canale alfa restituito come confine del ritaglio; mantenere lo stesso canvas non garantisce che ogni bordo o colore del primo piano resti invariato. I dettagli sono nella pagina del modello Background Remover.

Guarda prima un risultato reale

L'esempio della pagina del modello è un flacone contagocce smerigliato su uno sfondo grigio da studio, di 1024 × 1536 pixel. Sono i file prima e dopo di quella pagina; il «dopo» è mostrato qui sullo sfondo della pagina.

Eseguendo su questa coppia lo script di controllo delle sezioni successive si ottengono i numeri di un buon risultato: l'output ha un canale alfa, la dimensione coincide con l'origine, circa il 78% dei pixel è completamente trasparente, circa il 22% è pieno e solo circa lo 0.35% sono pixel di bordo semitrasparenti. Il riquadro del soggetto misura 335 × 1 234 pixel. Composto su uno sfondo blu navy scuro, la punta del contagocce, la ghiera spazzolata e le spalle in vetro smerigliato non hanno alcun alone chiaro.

Fai la chiamata

Installa spicyapi e pillow con python -m pip install spicyapi pillow. Imposta SPICY_API_KEY e IMAGE_URL sull'URL diretto della tua immagine di origine, poi esegui questo esempio. Ti chiede di confermare il prezzo, crea il task, lo attende, salva il ritaglio e scrive anteprime su sfondo chiaro e scuro.

import os
import urllib.request
import uuid
from io import BytesIO
from pathlib import Path

from PIL import Image
from spicyapi import SpicyClient, output_assets

client = SpicyClient()
model = "spicyapi/background-remover-v1/edit"
inputs = {"image_url": os.environ.get("IMAGE_URL", "https://cdn.spicyapi.ai/models/examples/inputs/e82b71db9e3d0e5f.png")}

quote = client.quote_task(model=model, input_data=inputs)
if input(f"Maximum ${quote['maxCharge']}. Create? [y/N] ") != "y":
    raise SystemExit("Stopped without creating a task.")

task = client.create_task(model=model, input_data=inputs, idempotency_key=str(uuid.uuid4()),
                          quote_id=quote["quoteId"], expected_cost=quote["estimatedCost"])
print("Task:", task["taskId"])  # keep this ID: a timeout does not cancel the task
task = client.wait_for_terminal(task["taskId"])
if task["state"] != "succeeded":
    raise RuntimeError(str(task.get("errorMessage", task["state"])))

asset = output_assets(task)[0]
request = urllib.request.Request(asset["url"], headers={"User-Agent": "SpicyAPI-Blog-Example/1.0"})
with urllib.request.urlopen(request, timeout=120) as response:
    data = response.read()
Path("cutout.png").write_bytes(data)

with Image.open(BytesIO(data)) as image:
    if image.format != "PNG":
        raise RuntimeError("Expected a PNG cutout.")
    rgba = image.convert("RGBA")
alpha = rgba.getchannel("A")
values = list(alpha.getdata())
print({"size": rgba.size, "alpha_min_max": alpha.getextrema(),
       "clear_fraction": sum(v <= 8 for v in values) / len(values),
       "solid_fraction": sum(v >= 247 for v in values) / len(values),
       "soft_fraction": sum(8 < v < 247 for v in values) / len(values),
       "subject_box": alpha.getbbox()})
for name, colour in [("light", "#f5f2e8"), ("dark", "#162235")]:
    Image.alpha_composite(Image.new("RGBA", rgba.size, colour), rgba).convert("RGB").save(name + ".jpg")

Per ritentare la stessa richiesta dopo una risposta persa, riusa la sua chiave di idempotenza invece di crearne una nuova (riferimento sull'idempotenza). Per il caricamento di file locali, vedi l'SDK Python e la documentazione sui media.

Verifica la trasparenza decodificando il file

Un'anteprima bianca non dimostra nulla. Potrebbe essere un vero ritaglio su una pagina bianca, un'immagine opaca con sfondo bianco o una scacchiera dipinta nei pixel. Decodifica il file e leggi il suo canale alfa. La specifica PNG definisce come viene memorizzato l'alfa; in pratica ti serve sapere se dopo la decodifica alcuni pixel possono essere trasparenti, non cosa dice il nome del file.

L'esempio riporta come è distribuito l'alfa e scrive composizioni su crema e blu navy scuro da esaminare con Pillow. Confronta le dimensioni che riporta con quelle della tua origine.

Fai attenzione alle soglie. Contare come opaco solo l'alfa 255 è fuorviante: nell'output del flacone contagocce circa il 14% dei pixel ha alfa da 1 a 254, ma quasi tutti sono 254, visivamente pieno. Considerando trasparente l'alfa fino a 8 e pieno quello da 247 in su, la frazione morbida resta per ciò che ti interessa davvero: bordi antialiasing, capelli e materiale davvero traslucido.

Come leggere il report:

• Un canale alfa assente, o un alpha_min_max di (255, 255), significa nessuna trasparenza: indaga sulla pipeline prima di controllare i bordi.
• Un clear_fraction vicino a 0 su una foto che aveva uno sfondo, o un solid_fraction vicino a 0, significa che il soggetto è andato perso o che il risultato è una nebbia.
• Una dimensione diversa indica di solito un'origine ruotata via EXIF o un ridimensionamento nel tuo codice, perché l'endpoint preserva le dimensioni.
• Un soft_fraction elevato è normale per vetro, tessuto e capelli e un campanello d'allarme per una tazza opaca. Imposta le soglie per categoria di prodotto dopo aver visto un set pilota, non un unico numero globale.
• Un riquadro del soggetto che tocca il bordo del canvas in una foto ritagliata con ampio margine suggerisce che sia stato mantenuto un secondo oggetto.

Prepara la foto senza cambiare il prodotto

Decidi cosa conta come prodotto prima di scattare o ritagliare: un nastro, la confezione e un'ombra di contatto sono dentro o fuori, e lo strumento non può indovinare un brief mai scritto. Non ridipingere un bordo scheggiato e non inventare un logo mancante; un difetto che l'annuncio deve mostrare resta nella foto.

• Ritaglia per eliminare gli oggetti concorrenti, ma lascia margine attorno a ogni estremità, così un manico o una tracolla non vengono tagliati prima che l'API li veda.
• Gli oggetti sovrapposti non si risolvono ritagliando, perché il confine nascosto va indovinato. Rifai lo scatto e indirizza sovrapposizioni, supporti espositivi trasparenti e soggetti tagliati a una corsia di eccezioni, così non intasano il lotto normale.
• Invia il file più pulito. Le riesportazioni JPEG ripetute lasciano artefatti a blocchi proprio dove il bordo ha bisogno di dettaglio; conserva una copia di lavoro senza perdita. Converti i profili colore in modo deliberato, perché una conversione disattenta cambia il colore del prodotto prima che qualcuno riveda il ritaglio.

Controlla il bordo dove verrà usata l'immagine

Metti il ritaglio sullo sfondo di destinazione reale, non solo sulla pagina in cui lo rivedi. Un ritaglio che sembra pulito su crema può mostrare un bordo pallido su blu navy scuro; quel bordo è colore dello sfondo di origine rimasto nei pixel parzialmente trasparenti. Controlla alla dimensione di consegna, per vedere se un difetto conta, e al 100%, per vederne la forma. Le due composizioni dello script usano crema e blu navy scuro; sostituiscile con i colori del tuo brand.

Guarda le zone in cui questo tipo di prodotto si riconosce, non ogni pixel allo stesso modo: l'interno del manico di una tazza, bordo e base, lacci e suole, setole, la punta del contagocce. Confronta origine, alfa e composizione alla stessa scala e con lo stesso ritaglio. Quando scarti un file, indica la caratteristica persa e la destinazione («apertura del manico riempita sulla composizione scura»), così la persona successiva sa se deve ritagliare, ritoccare o rifare lo scatto.

Tre situazioni richiedono una decisione, non un nuovo tentativo:

• Buchi dentro la sagoma. L'apertura di un manico o lo spazio tra i montanti di una sedia appartengono allo sfondo. Un controllo solo sul contorno può sembrare corretto anche se il buco è riempito. Verificalo sulla composizione scura.
• Ombre. Un'ombra di contatto ancora il prodotto; una lunga ombra proiettata trascina la texture dello sfondo nel ritaglio. Decidi se il master ne tiene una e se il layout disegnerà la propria. Se ne aggiungi una tua, ammorbidisci o rimuovi l'ombra già presente nell'origine, così due ombre non entrano in conflitto.
• Vetro e materiale traslucido. Il colore di una bottiglia include la luce dello sfondo che la attraversa, quindi nessun ritaglio può dare una bottiglia fisicamente corretta su ogni nuovo sfondo; un pallido riflesso da studio che sembra naturale sul bianco può sembrare sbagliato sullo scuro. Mantieni l'alfa parziale per plastica e tessuto traslucidi invece di forzarlo a 0 o 255, e non erodere l'intera maschera per eliminare un alone: assottigli il prodotto e perdi dettagli fini. Ritocca localmente su una copia.

Correggi l'errore nella fase che l'ha causato

Classificalo prima di rieseguire. Una chiamata ripetuta costa denaro e, per la maggior parte di questi casi, non cambia nulla.

Non c'è un prompt con cui spingere lo strumento, quindi le leve sono la foto in ingresso e ciò che fai dopo la chiamata. Se una categoria continua a fallire, cambia il modo in cui viene fotografata invece di ripetere le richieste.

Appiattisci per le destinazioni che richiedono uno sfondo pieno

I marketplace spesso vogliono un JPEG su bianco. Il JPEG non ha alfa, quindi esportare il master in JPEG riempie l'area trasparente con un colore predefinito che nessuno ha approvato. Appiattisci su un colore scelto, tieni il PNG come master e ridimensiona in modo uniforme (mai allungare larghezza e altezza in modo indipendente). Il light.jpg che lo script scrive è esattamente questo passaggio su crema; per il bianco, cambia il colore nel ciclo, oppure esporta un JPEG appiattito a parte dal tuo editor di immagini. Controlla il file piatto, non solo il master: ricampionamento, conversione colore e compressione aggiungono difetti propri. Se un alone compare solo dopo il caricamento nel tuo negozio o CMS, confronta i pixel decodificati di master, della tua esportazione e della miniatura della piattaforma; spesso la causa è il ridimensionamento o la ricompressione della piattaforma, non il ritaglio.

Quando un'altra strada è lo strumento giusto

Per un ritaglio semplice, Background Remover è la strada dal prezzo più basso di questa tabella e preserva la dimensione del canvas di origine. Usa un'altra strada quando ti serve qualcosa che deliberatamente non offre.

Se un modello generativo restituisce un PNG, ciò non lo rende trasparente: un PNG può contenere uno sfondo bianco opaco. Decodifica ogni risultato con lo stesso script. Dove contano i pixel esatti del prodotto (etichette, loghi, testo sulla confezione), preferisci la strada dell'estrazione a un ridisegno generativo.

Elabora un lotto senza sommergere i revisori

La chiamata al modello è economica e veloce; la revisione è il collo di bottiglia. Parti da un pilota di circa una dozzina di foto con diritti liberati che rappresentino il catalogo: un oggetto solido e pulito, uno con manico o apertura, uno lucido, uno con bordo fine, uno con un oggetto concorrente. Il pilota decide quali categorie passano con una revisione leggera e quali vanno sempre a una persona.

• Invia con concorrenza limitata e tieni una coda di download separata, così un download lento non innesca mai una nuova estrazione. Ritenta un download fallito sul risultato esistente finché il suo link è valido. La guida alla contropressione tratta il disegno della coda.
• Conserva per ogni revisione dell'origine il tuo ID asset, il checksum dell'origine, l'ID del task, la posizione dell'output e la decisione di revisione. Il solo SKU non basta: un prodotto ha più angolazioni e nuovi scatti.
• Tratta «succeeded» come «pronto per l'ispezione», mai come «pubblica». Esegui lo script automaticamente, poi manda a una persona solo i file segnalati e un campione. Le categorie che superano il pilota (oggetti solidi su sfondi neutri) possono passare a una corsia più leggera con campionamenti periodici per cogliere la deriva; gli articoli riflettenti, trasparenti e ambigui restano in revisione completa. Rivedi le immagini hero delle campagne prima degli angoli secondari, invece che nell'ordine di completamento.
• Per le notifiche di completamento, vedi la guida polling vs Webhook per i task asincroni; in entrambi i casi il risultato alimenta lo stesso passaggio di ispezione.
• Fermati quando i fallimenti hanno una causa comune. Dieci aperture di manico perse sono un'informazione sul set di origine, non dieci motivi per ritentare.

Quanto costa per immagine accettata

Cento ritagli costano $0.48 e mille costano $4.80. La cifra che conta è la spesa per master accettato. Come esempio di pianificazione, un lotto di 100 primi ritagli più 10 ritagliati di nuovo è 110 × $0.0048 = $0.528; se 95 superano la revisione, sono circa $0.0056 per immagine accettata.

Il tempo di revisione di solito costa più dell'API. Le leve utili sono a monte: se la maggior parte del tempo di revisione va alle bottiglie di vetro, un'illuminazione migliore per loro fa risparmiare più di qualsiasi differenza di prezzo. Un ritaglio completato che scarti è comunque un output completato e addebitato; i task falliti e scaduti rilasciano il loro blocco.

Tieni separati origine, master ed esportazioni

Tieni la foto di origine, il master PNG trasparente e ogni copia di consegna appiattita come file distinti, nominati per ciò che sono (per esempio <asset>-source, <asset>-cutout-master, <asset>-catalogue-cream), e tieni le versioni ritoccate separate dall'output intatto dell'API, così un alone successivo può essere ricondotto al ritaglio o all'esportazione. Conserva con ogni master la dimensione di destinazione approvata, così l'approvazione a dimensione scheda non viene scambiata per una a dimensione hero.

Registra ogni scarto sotto una sola categoria: soggetto sbagliato, caratteristica persa, frangia, frammento di sfondo residuo o difetto di esportazione. Un conteggio conta solo quando cambia qualcosa: una regola di ritaglio, una corsia manuale per il vetro, un preset di esportazione corretto. Dai al fotografo regole di scatto concrete («tieni visibile tutto il manico; nessuna scatola regalo dietro l'apertura», «sfondo più scuro per i prodotti chiari») invece di «rendilo più facile per l'IA».

Domande

Esiste un'API gratuita per rimuovere gli sfondi?

Non per questo endpoint: ogni output completato costa $0.0048, quindi un pilota da 100 foto costa $0.48. Se il requisito è la gratuità, ospitare in proprio un rimuovitore open source come rembg evita i costi per immagine, ma poi lo gestisci e lo regoli tu; la strada ospitata offre un endpoint stabile e un costo prevedibile.

Salvare il risultato come PNG rende trasparente lo sfondo?

No. Un PNG può contenere l'alfa, ma può anche contenere uno sfondo bianco opaco. Decodifica il file e leggi il canale alfa, poi controlla composizioni su sfondo chiaro e scuro. Rinominare un JPEG in .png non aggiunge nulla.

Posso dirgli di mantenere il manico, i capelli o l'ombra?

Non con questo task: il suo input è solo l'URL dell'immagine. Ritaglia l'origine, rifai lo scatto o ritocca localmente. Se vuoi un risultato guidato da prompt, usa una strada di modifica immagine dalla tabella sopra e verifica poi il prodotto e l'alfa.

Come dovrei iniziare?

Scegli un prodotto rappresentativo e una destinazione. Invia la foto, decodifica il PNG, controlla i bordi su due sfondi, appiattisci la derivata approvata e fai aprire la copia alla designer nel layout reale. Poi esegui i casi più difficili del tuo set pilota e annota quali richiedono un nuovo scatto o una corsia manuale prima di pianificare l'intero catalogo.

Lascia che un Agent gestisca la chiamata

Usa un Agent quando vuoi che prepari gli input e restituisca il risultato mentre tu approvi il prezzo e le scelte creative.

• CLI: con lo stesso oggetto di input salvato come input.json, usa npx @spicyapi/cli tasks create --model spicyapi/background-remover-v1/edit --input-file input.json --wait. La CLI fa confermare il prezzo; conserva l'ID del task restituito per il recupero.
• MCP: chiedi al tuo assistente di usare spicyapi_task_create per spicyapi/background-remover-v1/edit, poi spicyapi_task_wait. Il server MCP richiede la conferma del prezzo prima della creazione.
• Skill: installala con npx skills add spicyapi-ai/spicy-skill, poi chiedi a $spicyapi di eseguire lo stesso flusso di lavoro e di fermarsi per la tua approvazione. La Skill usa una connessione CLI o MCP già configurata.