Usa spicyapi/object-eraser-v1/edit con image_url e un breve prompt, una mask_url oppure entrambi. In una maschera il bianco significa rimuovere, il nero significa mantenere, e le sue dimensioni in pixel devono coincidere con quelle dell’originale. Il prezzo è 0,03 $ per immagine in uscita, a prescindere da quanti oggetti la richiesta rimuove. Il risultato mantiene le dimensioni originali della tela e riempie l’area selezionata con il contenuto della scena circostante.
Scegli tra prompt e maschera
Per un oggetto ben distinguibile e circondato da spazio, parti da una descrizione breve:
il bicchiere di carta bianco sul pavimento accanto alla gamba anteriore destra della sedia
Usa un sostantivo, un colore o un materiale visibile e una posizione. «Rendi la scena pulita e di livello premium» non indica cosa deve sparire. Il prompt può contenere da 1 a 1000 caratteri, ma una descrizione più lunga non rende la selezione più precisa.
| Situazione | Input da usare |
|---|---|
| Un solo bicchiere inconfondibile su un pavimento libero | prompt che nomina quel bicchiere |
| Due bicchieri simili, solo uno da togliere | mask_url sul bicchiere interessato |
| Cavo sottile, oppure oggetto a contatto con il bordo dell’inquadratura | mask_url; le descrizioni spesso li mancano |
| Una descrizione potrebbe indicare l’oggetto sbagliato | Invia entrambi, descrivendo e segnando lo stesso bersaglio |
| Serve una sedia ritagliata su sfondo trasparente | Rimozione dello sfondo |
| Serve più spazio attorno alla foto | Outpainting dopo la pulizia |
Se una descrizione non corrisponde a nulla, l’immagine torna invariata e l’attività risulta comunque riuscita. Confronta quindi l’output con l’originale prima di considerarlo una rimozione.
Illustrazione di possibili selezioni. Tutti gli oggetti segnati sono ancora presenti; non è un output dell’API.
Prova prima nel Playground
- Apri la pagina di Object Eraser, resta nella scheda Playground in vista Form e accedi con un account con credito per eseguire.
- Aggiungi la foto sotto Input image (JPG, PNG o WebP, fino a 10 MB). Trascina un file, incolla un link con Asset URL e Add URL, oppure sfoglia.
- Descrivi il bersaglio in Prompt, oppure aggiungi la tua immagine in bianco e nero sotto Mask, oppure compila entrambi. Il modulo richiede almeno uno dei due.
- Lascia Output format su PNG (JPEG e WebP producono file più piccoli) ed esegui. Il prezzo è 0,03 $ per immagine.
- Apri il risultato accanto all’originale e alla maschera e usa la tabella degli errori qui sotto se rimane qualcosa.
Il pannello Request body mostra lo stesso JSON che accetta l’API, quindi un prompt o una maschera che funzionano qui si possono copiare direttamente nel codice. Se qui fallisce, correggi il prompt o la maschera prima di scrivere una riga di codice.
Crea la maschera sull’immagine esatta che invierai
Se conosci già la regione (il riquadro di un rilevatore o una selezione in un’interfaccia), genera la maschera nel codice. Le sue dimensioni derivano dall’originale, quindi coincidono sempre:
from PIL import Image, ImageDraw
src = Image.open("source.jpg") # apply EXIF rotation and crop first
mask = Image.new("L", src.size, 0) # black = keep
bbox = (src.width // 4, src.height // 3, src.width // 2, src.height // 2)
# Example coordinates only: adjust this box to the unwanted object in your photo.
ImageDraw.Draw(mask).rectangle(bbox, fill=255) # white = remove
mask.save("mask.png")Per forme irregolari su un originale di 2400×1600, prepara in un editor di immagini una maschera di 2400×1600:
- Completa prima rotazione e ritaglio dell’originale e salva quell’immagine di lavoro.
- Aggiungi un livello nero a dimensione piena della tela e abbassane l’opacità mentre disegni, così il bersaglio resta visibile.
- Dipingi di bianco il bicchiere, compreso il suo bordo indesiderato e l’ombra di contatto, con un piccolo margine dove c’è spazio. La gamba della sedia resta nera.
- Riporta il livello a piena opacità ed esportalo da solo come PNG opaco in bianco e nero, non come foto attenuata né con annotazioni colorate.
- Sovrapponi la maschera esportata all’originale di lavoro e controlla l’area bianca.
Proporzioni uguali non bastano: entrambi i file devono avere stessa larghezza, altezza, ritaglio e orientamento. Una forma leggermente generosa funziona dove non c’è nient’altro vicino. La maschera d’esempio della pagina del modello, per uno scaffale sul bordo dell’inquadratura, è una tela nera grande quanto la foto con un solo semplice rettangolo bianco sullo scaffale.
Ombre e riflessi possono stare fuori dalla sagoma dell’oggetto. Dipingi un riflesso indesiderato come area bianca a sé. Dove l’ombra del bicchiere si sovrappone all’ombra di appoggio della sedia, non dipingere di bianco tutta la macchia scura, altrimenti la sedia può sembrare sospesa. La maschera indica cosa rimuovere; non fornisce il pavimento nascosto né la geometria del prodotto.
Esegui le rimozioni grandi o sovrapposte in passaggi separati, costruendo ogni maschera sull’output precedente già accettato. Due piccoli oggetti in una sola richiesta costano 0,03 $; due richieste separate costano 0,06 $. Tieni abbinati i nomi dei file di maschera e immagine, così una selezione vecchia non modifica in silenzio una foto più recente.
Poi eseguilo dal codice
Installa l’SDK Python (pip install spicyapi), imposta SPICY_API_KEY nell’ambiente del tuo server ed esegui la richiesta qui sotto. Usa la foto d’esempio della pagina del modello, quindi funziona così com’è. I file sul tuo computer passano da client.upload_file e tornano come indirizzo spicy://. Per una maschera, aggiungi "mask_url" con il tuo file, della stessa dimensione in pixel della foto.
import uuid
from spicyapi import SpicyClient, output_assets
client = SpicyClient() # reads SPICY_API_KEY from the environment
task = client.create_task(
model="spicyapi/object-eraser-v1/edit",
input_data={
"image_url": "https://cdn.spicyapi.ai/models/examples/inputs/fbc8d531c80e6d0d.jpeg",
"prompt": "the wooden ladle lying across the sauna stones at the left",
"output_format": "png",
},
idempotency_key=str(uuid.uuid4()),
)
final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
print(output_assets(final)[0]["url"]) # copy the image to your own storage nowCaricamenti, creazione, attesa, download, nuovi tentativi e codici di errore sono trattati nella guida alle attività e nel riferimento dell’SDK Python. I file generati vengono conservati al massimo 14 giorni, quindi copia il risultato nel tuo archivio.
Oppure lascia che lo esegua un agente
Quando deve essere un assistente a eseguire la modifica, tutti e tre gli strumenti ufficiali mostrano il prezzo e chiedono conferma prima di una chiamata a pagamento.
- CLI. Carica la foto e la maschera, poi crea l’attività:
``bash spicyapi files upload photo.jpg spicyapi tasks create --model spicyapi/object-eraser-v1/edit --input-file input.json --wait ``
Inserisci gli indirizzi spicy:// restituiti in input.json come image_url e mask_url. Vedi la documentazione della CLI; npx @spicyapi/cli funziona senza installazione.
- Server MCP. Aggiungi il server MCP al tuo assistente, poi chiedi: «Rimuovi il bicchiere di carta bianco da questa foto con Object Eraser; il file è in /path/to/photo.jpg». Carica il file con
spicyapi_upload_file, chiamaspicyapi_task_create, che si ferma per la conferma del prezzo, e poispicyapi_task_wait. - Skill.
npx skills add spicyapi-ai/spicy-skillinstalla l’Agent Skill, con cui un assistente di programmazione legge lo schema aggiornato del modello invece di indovinare i campi.
Correggi l’errore specifico che vedi
Apri erased.png accanto all’originale e alla maschera. Controlla prima dove la selezione incontra il contenuto mantenuto, poi il centro del riempimento.
| Risultato | Cosa cambiare |
|---|---|
| Il bicchiere è ancora lì dopo una richiesta con solo prompt | Passa a una maschera su quel bicchiere. |
| Il cavo resta al bordo | Dipingi di bianco tutta la sua lunghezza visibile su una maschera a piena risoluzione. |
| Rimane un contorno tenue | Estendi leggermente la selezione oltre il bordo dell’oggetto, senza coprire i bordi vicini del prodotto. |
| Il bicchiere è sparito ma resta un ovale scuro | Aggiungi alla maschera l’ombra di contatto del bicchiere, separata dall’ombra della sedia. |
| Parte della gamba della sedia viene ricostruita male | Riduci la maschera dove copre la gamba. Se il bicchiere nasconde la gamba stessa, usa un’altra foto di partenza. |
| Un confronto per differenza mostra tutta l’immagine cambiata | Allinea prima rotazione e dimensioni; il solo rumore di compressione non è una modifica. Controlla punti di riferimento fissi. |
| La richiesta restituisce 400 | Verifica se mancano prompt e maschera, oppure se invii campi che il modello non ha, come strength, mask_blur o transparent_background. Per una richiesta rifiutata non viene addebitato nulla. |
Illustrazione dell’ispezione di ombre e riflessi. Non mostra una rimozione completata.
Il modello ricostruisce lo sfondo nascosto; non può rivelare cosa ci fosse davvero dietro l’oggetto. Per la scheda di un prodotto, non accettare un giunto della sedia inventato o una cucitura dell’imbottitura alterata solo perché il pavimento sembra più pulito. Rifai la foto quando l’oggetto rimosso nasconde un dettaglio che la scheda deve mostrare con precisione.
SpicyAPI non esegue alcun controllo di sicurezza su questo modello; è il modello stesso a decidere cosa restituire.
Conserva l’originale e la maschera insieme all’output accettato, e aggiungi un altro passaggio solo per uno specifico oggetto rimasto. La scheda Examples della pagina del modello mostra risultati reali prima/dopo.
