API usuwania tła: dostarczaj przezroczyste PNG produktów

Masz kilkaset zdjęć produktów zrobionych na szarych stołach i parapetach, a sklep, marketplace lub grafik chce każde z nich jako przezroczysty PNG. SpicyAPI Background Remover robi to jednym wywołaniem: wysyłasz adres URL zdjęcia i dostajesz główny obiekt na przezroczystym PNG o oryginalnej szerokości i wysokości. Reszta pracy należy do Ciebie: sprawdzić, czy plik naprawdę ma kanał alfa, ocenić krawędzie na tłach, na których trafi, i wyeksportować spłaszczone kopie, jakich wymaga każde miejsce docelowe.

Najpierw wypróbuj w Playground

Otwórz Playground background-remover-v1. Upuść zdjęcie produktu w polu Input image, sprawdź cenę i naciśnij Run model. Obejrzyj przezroczysty wynik na jasnym i ciemnym tle, zanim użyjesz tego samego zdjęcia w kodzie.

Co endpoint przyjmuje i zwraca

Wynik zachowuje wymiary płótna źródłowego, więc możesz umieścić wycięty obiekt na nowym tle bez zmiany skali. Jako granicy wycięcia używaj zwróconego kanału alfa; zachowanie tego samego płótna nie gwarantuje, że każda krawędź ani kolor pierwszego planu pozostaną bez zmian. Szczegóły są na stronie modelu Background Remover.

Najpierw zobacz prawdziwy wynik

Przykład z samej strony modelu to szronione szklane opakowanie z zakraplaczem na szarym tle studyjnym, 1024 × 1536 pikseli. To pliki przed i po z tej strony; „po” jest tu pokazane na tle strony.

Uruchomienie na tej parze skryptu kontrolnego z kolejnych sekcji daje liczby dobrego wyniku: wyjście ma kanał alfa, rozmiar zgadza się ze źródłem, około 78% pikseli jest całkowicie przezroczystych, około 22% jest pełnych i tylko około 0,35% to półprzezroczyste piksele krawędzi. Ramka obiektu ma 335 × 1 234 piksele. Po złożeniu na ciemnogranatowym tle końcówka zakraplacza, szczotkowany kołnierz i szronione szklane ramiona nie mają jasnej obwódki.

Wykonaj wywołanie

Zainstaluj spicyapi i pillow poleceniem python -m pip install spicyapi pillow. Ustaw SPICY_API_KEY oraz IMAGE_URL na bezpośredni adres URL obrazu źródłowego, a potem uruchom ten przykład. Prosi o potwierdzenie ceny, tworzy zadanie, czeka na nie, zapisuje wycięty obiekt i zapisuje podglądy na jasnym i ciemnym tle.

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

Aby ponowić to samo żądanie po utracie odpowiedzi, użyj ponownie jego klucza idempotentności zamiast tworzyć nowy (opis idempotentności). Informacje o wysyłaniu plików lokalnych znajdziesz w Python SDK i dokumentacji mediów.

Sprawdź przezroczystość, dekodując plik

Biały podgląd niczego nie dowodzi. Może to być prawdziwe wycięcie na białej stronie, nieprzezroczysty obraz z białym tłem albo szachownica namalowana w pikselach. Zdekoduj plik i odczytaj jego kanał alfa. Specyfikacja PNG określa, jak przechowywane jest alfa; w praktyce musisz wiedzieć, czy po dekodowaniu część pikseli może być przezroczysta, a nie co mówi nazwa pliku.

Przykład podaje rozkład alfa i zapisuje kompozycje na kremowym i ciemnogranatowym tle do przeglądu z użyciem Pillow. Porównaj podane wymiary ze źródłem.

Zwróć uwagę na progi. Liczenie jako nieprzezroczystego tylko alfa 255 wprowadza w błąd: w wyniku dla butelki z zakraplaczem około 14% pikseli ma alfa od 1 do 254, ale prawie wszystkie to 254, czyli wizualnie pełne. Traktowanie alfa do 8 jako przezroczystego, a od 247 jako pełnego zostawia frakcję miękką dla tego, na czym naprawdę Ci zależy: wygładzonych krawędzi, włosów i naprawdę półprzezroczystego materiału.

Jak czytać raport:

• Brak kanału alfa albo alpha_min_max równe (255, 255) oznacza brak przezroczystości: zbadaj potok, zanim zajmiesz się krawędziami.
• clear_fraction bliskie 0 na zdjęciu, które miało tło, albo solid_fraction bliskie 0 oznacza, że obiekt zginął albo wynik jest mgłą.
• Niezgodność rozmiaru zwykle wskazuje na źródło obrócone przez EXIF albo zmianę rozmiaru we własnym kodzie, bo endpoint zachowuje wymiary.
• Duże soft_fraction jest normalne dla szkła, tkaniny i włosów, a sygnałem ostrzegawczym dla matowego kubka. Progi ustaw osobno dla kategorii produktów po obejrzeniu zestawu pilotażowego, a nie jedną liczbą globalną.
• Ramka obiektu dotykająca krawędzi płótna na zdjęciu, które przyciąłeś z zapasem, sugeruje, że zachowano drugi obiekt.

Przygotuj zdjęcie bez zmieniania produktu

Zanim zrobisz zdjęcie albo je przytniesz, zdecyduj, co jest produktem: wstążka, opakowanie i cień kontaktowy są w kadrze albo poza nim, a narzędzie nie odgadnie wytycznych, których nigdy nie spisano. Nie retuszuj wyszczerbionej krawędzi i nie dorabiaj brakującego logo; wada, którą oferta musi pokazać, zostaje na zdjęciu.

• Przytnij, by usunąć konkurujące obiekty, ale zostaw margines wokół każdego skrajnego elementu, aby uchwyt lub pasek nie został obcięty, zanim zobaczy go API.
• Nakładających się obiektów nie naprawi przycięcie, bo ukrytą granicę trzeba by zgadywać. Zrób zdjęcie od nowa, a nakładania, przezroczyste stojaki ekspozycyjne i obcięte obiekty kieruj na osobny tor wyjątków, aby nie zatykały zwykłej partii.
• Wysyłaj najczystszy plik. Wielokrotne eksporty JPEG zostawiają artefakty blokowe dokładnie tam, gdzie krawędź potrzebuje szczegółu; zachowaj bezstratną kopię roboczą. Profile kolorów konwertuj świadomie, bo nieuważna konwersja zmienia kolor produktu, zanim ktokolwiek obejrzy wycięcie.

Sprawdź krawędź tam, gdzie obraz będzie użyty

Połóż wycięty obiekt na prawdziwym tle docelowym, a nie tylko na stronie, na której go oceniasz. Wycięcie, które na kremowym wygląda czysto, na ciemnogranatowym może pokazać jasną obwódkę; ta obwódka to kolor tła źródłowego pozostały w częściowo przezroczystych pikselach. Sprawdź w rozmiarze dostawy, by zobaczyć, czy wada ma znaczenie, i przy 100%, by zobaczyć jej kształt. Dwie kompozycje skryptu używają koloru kremowego i ciemnogranatowego; zamień je na kolory swojej marki.

Patrz na miejsca, po których rozpoznaje się ten rodzaj produktu, a nie na każdy piksel jednakowo: wnętrze ucha kubka, brzeg i stopkę, sznurówki i podeszwy, włosie, końcówkę zakraplacza. Porównuj źródło, alfa i kompozycję w tej samej skali i kadrze. Odrzucając plik, nazwij utraconą cechę i miejsce docelowe („otwór ucha wypełniony na ciemnej kompozycji”), aby kolejna osoba wiedziała, czy przyciąć, wyretuszować, czy sfotografować od nowa.

Trzy sytuacje wymagają decyzji, a nie ponownej próby:

• Otwory wewnątrz sylwetki. Otwór ucha albo przerwa między szczeblami krzesła należą do tła. Kontrola samego obrysu może wyglądać dobrze, choć otwór jest wypełniony. Sprawdź go na ciemnej kompozycji.
• Cienie. Cień kontaktowy osadza produkt; długi cień rzucany wciąga do wycięcia fakturę tła. Zdecyduj, czy master zachowuje jakiś cień i czy układ narysuje własny. Jeśli dodajesz własny, złagodź lub usuń cień obecny już w źródle, aby dwa się nie kłóciły.
• Szkło i materiał półprzezroczysty. Kolor butelki obejmuje światło tła przechodzące przez nią, więc żadne wycięcie nie da fizycznie poprawnej butelki na każdym nowym tle; blade studyjne odbicie, które na bieli wygląda naturalnie, na ciemnym może wyglądać źle. Dla półprzezroczystego plastiku i tkaniny zachowaj częściowe alfa zamiast obcinać je progiem do 0 lub 255 i nie erozuj całej maski, by usunąć obwódkę: ścieniasz produkt i tracisz drobne cechy. Retuszuj lokalnie na kopii.

Napraw błąd na etapie, który go spowodował

Zaklasyfikuj go, zanim uruchomisz ponownie. Powtórzone wywołanie kosztuje i w większości tych przypadków niczego nie zmienia.

Nie ma promptu, którym można by popchnąć narzędzie, więc dźwigniami są zdjęcie wejściowe i to, co robisz po wywołaniu. Jeśli jedna kategoria ciągle zawodzi, zmień sposób jej fotografowania zamiast powtarzać żądania.

Spłaszcz dla miejsc docelowych wymagających pełnego tła

Marketplace’y często chcą JPEG na białym. JPEG nie ma alfa, więc eksport mastera do JPEG wypełnia obszar przezroczysty domyślnym kolorem, którego nikt nie zatwierdził. Spłaszcz na wybranym kolorze, zachowaj PNG jako master i zmieniaj rozmiar jednolicie (nigdy nie rozciągaj szerokości i wysokości niezależnie). Plik light.jpg, który zapisuje skrypt, to dokładnie ten krok na kremowym; dla bieli zmień kolor w pętli albo wyeksportuj osobny spłaszczony JPEG z edytora obrazów. Sprawdzaj plik płaski, nie tylko master: próbkowanie, konwersja kolorów i kompresja dodają własne wady. Jeśli obwódka pojawia się dopiero po wysłaniu do sklepu lub CMS-a, porównaj zdekodowane piksele mastera, własnego eksportu i miniatury platformy; przyczyną często jest zmiana rozmiaru albo ponowna kompresja platformy, a nie wycięcie.

Kiedy inna droga jest właściwym narzędziem

Do zwykłego wycięcia Background Remover jest najtańszą drogą w tej tabeli i zachowuje rozmiar płótna źródłowego. Użyj innej drogi, gdy potrzebujesz czegoś, czego celowo nie oferuje.

Jeśli model generatywny zwraca PNG, nie znaczy to, że jest przezroczysty: PNG może mieć nieprzezroczyste białe tło. Każdy wynik dekoduj tym samym skryptem. Tam, gdzie liczą się dokładne piksele produktu (etykiety, logo, tekst na opakowaniu), wybieraj drogę ekstrakcji zamiast generatywnego przerysowania.

Przepuść partię, nie zalewając recenzentów

Wywołanie modelu jest tanie i szybkie; wąskim gardłem jest przegląd. Zacznij od pilotażu na około tuzinie zdjęć z uregulowanymi prawami, reprezentujących katalog: jeden czysty pełny obiekt, jeden z uchwytem lub otworem, jeden błyszczący, jeden z delikatną krawędzią, jeden z konkurującym obiektem. Pilotaż rozstrzyga, które kategorie przechodzą lekki przegląd, a które zawsze trafiają do człowieka.

• Wysyłaj z ograniczoną współbieżnością i prowadź osobną kolejkę pobierania, aby wolne pobieranie nigdy nie uruchomiło ponownej ekstrakcji. Nieudane pobieranie ponawiaj względem istniejącego wyniku, dopóki jego link jest ważny. Przewodnik o przeciwciśnieniu opisuje projekt kolejki.
• Przechowuj dla każdej rewizji źródła własny identyfikator zasobu, sumę kontrolną źródła, identyfikator zadania, lokalizację wyniku i decyzję z przeglądu. Sam SKU nie wystarcza: jeden produkt ma kilka ujęć i powtórne sesje.
• Traktuj „succeeded” jako „gotowe do inspekcji”, nigdy jako „publikuj”. Uruchamiaj skrypt automatycznie, a potem do człowieka wysyłaj tylko oznaczone pliki i próbkę. Kategorie, które przejdą pilotaż (pełne obiekty na neutralnych tłach), mogą trafić na lżejszy tor z okresowym próbkowaniem wychwytującym dryf; przedmioty odbijające światło, przezroczyste i niejednoznaczne zostają przy pełnym przeglądzie. Przeglądaj główne obrazy kampanii przed ujęciami pobocznymi, a nie w kolejności ukończenia.
• O powiadomieniach o zakończeniu przeczytasz w przewodniku polling vs Webhook dla zadań asynchronicznych; tak czy inaczej wynik trafia do tego samego kroku inspekcji.
• Wstrzymaj pracę, gdy błędy mają wspólną przyczynę. Dziesięć utraconych otworów ucha to informacja o zestawie źródeł, a nie dziesięć powodów do ponownej próby.

Ile kosztuje zaakceptowany obraz

Sto wycięć kosztuje 0,48 $, a tysiąc kosztuje 4,80 $. Liczy się wydatek na zaakceptowany master. Jako przykład planistyczny: partia 100 pierwszych wycięć plus 10 ponownie przyciętych to 110 × 0,0048 $ = 0,528 $; jeśli 95 przejdzie przegląd, wychodzi około 0,0056 $ za zaakceptowany obraz.

Czas przeglądu zwykle kosztuje więcej niż API. Przydatne dźwignie leżą wcześniej: jeśli większość czasu przeglądu pochłaniają szklane butelki, lepiej oświetlone ujęcie dla nich oszczędzi więcej niż jakakolwiek różnica w cenie. Zakończone wycięcie, które odrzucasz, nadal jest zakończonym, rozliczonym wynikiem; zadania nieudane i wygasłe zwalniają swoją blokadę.

Trzymaj osobno źródło, master i eksporty

Przechowuj zdjęcie źródłowe, przezroczysty master PNG i każdą spłaszczoną kopię dostawczą jako osobne pliki, nazwane zgodnie z tym, czym są (na przykład <asset>-source, <asset>-cutout-master, <asset>-catalogue-cream), a wersje retuszowane trzymaj z dala od nietkniętego wyniku API, aby późniejszą obwódkę dało się przypisać wycięciu albo eksportowi. Zapisuj przy każdym masterze zatwierdzony rozmiar docelowy, aby akceptacja w rozmiarze karty nie została pomylona z akceptacją w rozmiarze hero.

Każde odrzucenie zapisuj w jednej kategorii: zły obiekt, utracona cecha, obwódka, pozostały fragment tła lub wada eksportu. Liczba ma znaczenie tylko wtedy, gdy coś zmienia: regułę przycinania, ręczny tor dla szkła, poprawiony preset eksportu. Dawaj fotografowi konkretne zasady zdjęć („zostaw widoczny cały uchwyt; żadnego pudełka prezentowego za otworem”, „ciemniejsze tło dla jasnych produktów”) zamiast „ułatw to AI”.

Pytania

Czy istnieje darmowe API do usuwania tła?

Nie dla tego endpointu: każde zakończone wyjście kosztuje 0,0048 $, więc pilotaż na 100 zdjęciach kosztuje 0,48 $. Jeśli wymagane jest „za darmo”, samodzielne hostowanie otwartego narzędzia, takiego jak rembg, pozwala uniknąć opłat za obraz, ale wtedy sam je uruchamiasz i dostrajasz; droga hostowana daje stabilny endpoint i przewidywalny koszt.

Czy zapisanie wyniku jako PNG czyni tło przezroczystym?

Nie. PNG może zawierać alfa, ale może też mieć nieprzezroczyste białe tło. Zdekoduj plik i odczytaj kanał alfa, a potem obejrzyj kompozycje na jasnym i ciemnym tle. Zmiana nazwy JPEG na .png niczego nie dodaje.

Czy mogę kazać mu zachować uchwyt, włosy lub cień?

Nie w tym zadaniu: jego wejściem jest tylko URL obrazu. Przytnij źródło, sfotografuj od nowa albo retuszuj lokalnie. Jeśli chcesz wyniku sterowanego promptem, użyj drogi edycji obrazu z powyższej tabeli i potem sprawdź produkt oraz alfa.

Jak zacząć?

Wybierz jeden reprezentatywny produkt i jedno miejsce docelowe. Wyślij zdjęcie, zdekoduj PNG, sprawdź krawędzie na dwóch tłach, spłaszcz zatwierdzoną pochodną i poproś grafika o otwarcie jej w prawdziwym układzie. Potem przepuść trudniejsze elementy zestawu pilotażowego i zapisz, które wymagają nowej sesji zdjęciowej lub ręcznego toru, zanim zaplanujesz cały katalog.

Pozwól, by Agent zajął się wywołaniem

Użyj Agenta, gdy chcesz, aby przygotował wejścia i zwrócił wynik, a Ty zatwierdzasz cenę i decyzje twórcze.

• CLI: po zapisaniu tego samego obiektu wejściowego jako input.json użyj npx @spicyapi/cli tasks create --model spicyapi/background-remover-v1/edit --input-file input.json --wait. CLI prosi o potwierdzenie ceny; zachowaj zwrócony identyfikator zadania do odzyskiwania.
• MCP: poproś asystenta, aby użył spicyapi_task_create dla spicyapi/background-remover-v1/edit, a następnie spicyapi_task_wait. Serwer MCP przed utworzeniem żąda potwierdzenia ceny.
• Skill: zainstaluj poleceniem npx skills add spicyapi-ai/spicy-skill, a potem poproś $spicyapi, aby wykonał ten sam przepływ pracy i zatrzymał się na Twoje zatwierdzenie. Skill korzysta ze skonfigurowanego połączenia CLI lub MCP.