Hintergrundentfernung per API: transparente Produkt-PNGs liefern

Sie haben einige hundert Produktfotos auf grauen Tischen und Fensterbänken, und der Shop, der Marktplatz oder die Designerin braucht jedes davon als transparentes PNG. SpicyAPI Background Remover erledigt das mit einem Aufruf: Sie senden eine Foto-URL und erhalten das Hauptmotiv auf einem transparenten PNG in der ursprünglichen Breite und Höhe zurück. Der Rest bleibt bei Ihnen: prüfen, ob die Datei wirklich einen Alphakanal hat, die Kanten auf den Hintergründen kontrollieren, auf denen sie landen wird, und die flachen Kopien exportieren, die jedes Ziel verlangt.

Zuerst im Playground ausprobieren

Öffnen Sie den background-remover-v1 Playground. Ziehen Sie ein Produktfoto in Input image, prüfen Sie den Preis und klicken Sie auf Run model. Sehen Sie sich das transparente Ergebnis vor hellem und dunklem Hintergrund an, bevor Sie dasselbe Foto im Code verwenden.

Was der Endpoint annimmt und zurückgibt

Die Ausgabe behält die Maße der Quellfläche, sodass Sie den Freisteller ohne Skalierung über einen neuen Hintergrund legen können. Verwenden Sie den zurückgegebenen Alphakanal als Schnittgrenze; dieselbe Fläche garantiert nicht, dass jede Vordergrundkante oder Farbe unverändert bleibt. Details stehen auf der Modellseite von Background Remover.

Zuerst ein echtes Ergebnis ansehen

Das Beispiel auf der Modellseite ist eine Pipettenflasche aus Milchglas vor einem grauen Studiohintergrund, 1024 × 1536 Pixel. Das sind die Vorher- und Nachher-Dateien von dieser Seite; das „Nachher“ wird hier über dem Seitenhintergrund gezeigt.

Wenn Sie das Prüfskript aus den nächsten Abschnitten auf dieses Paar anwenden, erhalten Sie die Zahlen, die ein gutes Ergebnis ausmachen: Die Ausgabe hat einen Alphakanal, die Größe stimmt mit der Quelle überein, etwa 78 % der Pixel sind vollständig klar, etwa 22 % sind deckend und nur etwa 0.35 % sind halbtransparente Kantenpixel. Die Motivbox misst 335 × 1 234 Pixel. Auf einem dunklen marineblauen Hintergrund zeigen die Pipettenspitze, der gebürstete Kragen und die Schultern aus Milchglas keinen hellen Saum.

Den Aufruf ausführen

Installieren Sie spicyapi und pillow mit python -m pip install spicyapi pillow. Setzen Sie SPICY_API_KEY und IMAGE_URL auf die direkte URL Ihres Quellbilds und führen Sie dann dieses Beispiel aus. Es bittet Sie, den Preis zu bestätigen, erstellt die Aufgabe, wartet darauf, speichert den Freisteller und schreibt Vorschauen auf hellem und dunklem Hintergrund.

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

Um dieselbe Anfrage nach einer verlorenen Antwort zu wiederholen, verwenden Sie ihren Idempotenzschlüssel erneut, statt einen neuen zu erzeugen (Referenz zur Idempotenz). Für lokale Datei-Uploads siehe das Python SDK und die Mediendokumentation.

Transparenz prüfen, indem Sie die Datei dekodieren

Eine weiße Vorschau beweist nichts. Es kann ein echter Freisteller auf einer weißen Seite sein, ein deckendes Bild mit weißem Hintergrund oder ein Schachbrettmuster, das in die Pixel gemalt wurde. Dekodieren Sie die Datei und lesen Sie ihren Alphakanal. Die PNG-Spezifikation legt fest, wie Alpha gespeichert wird; in der Praxis müssen Sie wissen, ob einige Pixel nach dem Dekodieren transparent sein können, nicht, was der Dateiname behauptet.

Das Beispiel gibt aus, wie Alpha verteilt ist, und schreibt Kompositionen auf Cremeweiß und dunklem Marineblau zur Prüfung mit Pillow. Vergleichen Sie die gemeldeten Maße mit Ihrer Quelle.

Beachten Sie die Schwellenwerte. Nur Alpha 255 als deckend zu zählen, führt in die Irre: Bei der Pipettenflasche liegen etwa 14 % der Pixel bei Alpha 1 bis 254, fast alle davon aber bei 254, was optisch deckend ist. Wenn Sie Alpha bis 8 als klar und ab 247 als deckend werten, bleibt der weiche Anteil für das übrig, worauf es Ihnen wirklich ankommt: geglättete Kanten, Haare und tatsächlich durchscheinendes Material.

So lesen Sie den Bericht:

• Ein fehlender Alphakanal oder ein alpha_min_max von (255, 255) bedeutet keine Transparenz: Untersuchen Sie die Pipeline, bevor Sie Kanten prüfen.
• Ein clear_fraction nahe 0 bei einem Foto, das einen Hintergrund hatte, oder ein solid_fraction nahe 0 bedeutet, dass das Motiv verloren ging oder das Ergebnis ein Schleier ist.
• Eine abweichende Größe deutet meist auf eine per EXIF gedrehte Quelle oder eine Skalierung in Ihrem eigenen Code hin, denn der Endpoint erhält die Maße.
• Ein hoher soft_fraction ist bei Glas, Stoff und Haaren normal und bei einer matten Tasse ein Warnsignal. Legen Sie Schwellenwerte pro Produktkategorie fest, nachdem Sie sich eine Pilotgruppe angesehen haben, nicht eine einzige globale Zahl.
• Eine Motivbox, die den Bildrand berührt, obwohl Sie das Foto großzügig zugeschnitten haben, lässt vermuten, dass ein zweites Objekt erhalten blieb.

Das Foto vorbereiten, ohne das Produkt zu verändern

Legen Sie vor dem Fotografieren oder Zuschneiden fest, was als Produkt zählt: Eine Schleife, die Verpackung und ein Kontaktschatten gehören entweder dazu oder nicht, und das Tool kann keinen Auftrag erraten, der nie formuliert wurde. Retuschieren Sie keinen abgeplatzten Rand und erfinden Sie kein fehlendes Logo; ein Mangel, den das Angebot zeigen muss, bleibt im Foto.

• Schneiden Sie zu, um störende Objekte zu entfernen, lassen Sie aber um jedes äußerste Ende Rand, damit ein Henkel oder Riemen nicht abgeschnitten wird, bevor die API ihn sieht.
• Überlappende Objekte lassen sich durch Zuschneiden nicht beheben, weil die verdeckte Grenze erraten werden muss. Fotografieren Sie neu und leiten Sie Überlappungen, transparente Displayständer und angeschnittene Motive in eine Ausnahmespur, damit sie den normalen Batch nicht verstopfen.
• Senden Sie die sauberste Datei. Wiederholte JPEG-Exporte hinterlassen Blockartefakte genau dort, wo die Kante Detail braucht; bewahren Sie eine verlustfreie Arbeitskopie auf. Konvertieren Sie Farbprofile bewusst, denn eine nachlässige Konvertierung verändert die Produktfarbe, bevor jemand den Freisteller prüft.

Die Kante dort prüfen, wo das Bild verwendet wird

Legen Sie den Freisteller über den echten Zielhintergrund, nicht nur über die Seite, auf der Sie ihn prüfen. Ein Freisteller, der auf Creme sauber aussieht, kann auf dunklem Marineblau einen hellen Rand zeigen; dieser Rand ist Farbe des Quellhintergrunds, die in teiltransparenten Pixeln zurückgeblieben ist. Prüfen Sie in der Auslieferungsgröße, um zu sehen, ob ein Fehler ins Gewicht fällt, und bei 100 %, um seine Form zu sehen. Die beiden Kompositionen des Skripts verwenden Creme und dunkles Marineblau; ersetzen Sie sie durch Ihre Markenfarben.

Achten Sie auf die Bereiche, an denen diese Art Produkt erkannt wird, nicht auf jedes Pixel gleich: das Innere eines Tassenhenkels, Rand und Fuß, Schnürsenkel und Sohlen, Borsten, die Pipettenspitze. Vergleichen Sie Quelle, Alpha und Komposition im gleichen Maßstab und Ausschnitt. Wenn Sie eine Datei ablehnen, nennen Sie das verlorene Merkmal und das Ziel („Henkelöffnung auf dunkler Komposition gefüllt“), damit die nächste Person weiß, ob sie zuschneiden, retuschieren oder neu fotografieren muss.

Drei Situationen verlangen eine Entscheidung statt eines erneuten Versuchs:

• Löcher innerhalb der Silhouette. Eine Henkelöffnung oder der Zwischenraum zwischen Stuhlsprossen gehört zum Hintergrund. Eine Prüfung nur der Umrisslinie kann richtig aussehen, obwohl das Loch gefüllt ist. Prüfen Sie es auf der dunklen Komposition.
• Schatten. Ein Kontaktschatten erdet ein Produkt; ein langer Schlagschatten zieht Hintergrundtextur in den Freisteller. Entscheiden Sie, ob das Master einen behält und ob das Layout seinen eigenen zeichnet. Wenn Sie einen eigenen hinzufügen, mildern oder entfernen Sie den Schatten, der schon in der Quelle ist, damit sich nicht zwei widersprechen.
• Glas und durchscheinendes Material. Die Farbe einer Flasche enthält durchgelassenes Hintergrundlicht, daher kann kein Freisteller auf jedem neuen Hintergrund eine physikalisch richtige Flasche liefern; eine blasse Studioreflexion, die auf Weiß natürlich wirkt, kann auf Dunkel falsch aussehen. Behalten Sie bei durchscheinendem Kunststoff und Stoff das partielle Alpha, statt es auf 0 oder 255 zu schneiden, und erodieren Sie nicht die ganze Maske, um einen Lichtsaum zu entfernen: Sie machen das Produkt dünner und verlieren feine Merkmale. Retuschieren Sie lokal an einer Kopie.

Den Fehler in der Phase beheben, die ihn verursacht hat

Ordnen Sie ihn ein, bevor Sie neu ausführen. Ein wiederholter Aufruf kostet Geld und ändert bei den meisten dieser Fälle nichts.

Es gibt keinen Prompt, mit dem Sie das Tool anstoßen könnten; Ihre Stellschrauben sind also das Eingabefoto und das, was Sie nach dem Aufruf tun. Wenn eine Kategorie immer wieder scheitert, ändern Sie, wie sie fotografiert wird, statt Anfragen zu wiederholen.

Für Ziele mit deckendem Hintergrund auf eine Farbe reduzieren

Marktplätze wollen oft ein JPEG auf Weiß. JPEG kennt kein Alpha; exportieren Sie das Master als JPEG, füllt eine Standardfarbe, die niemand freigegeben hat, den transparenten Bereich. Reduzieren Sie auf eine gewählte Farbe, behalten Sie das PNG als Master und skalieren Sie gleichmäßig (Breite und Höhe nie unabhängig voneinander dehnen). Die light.jpg, die das Skript schreibt, ist genau dieser Schritt auf Creme; für Weiß ändern Sie die Farbe in der Schleife oder exportieren ein separates reduziertes JPEG aus Ihrem Bildeditor. Prüfen Sie die flache Datei, nicht nur das Master: Neuberechnung, Farbkonvertierung und Kompression bringen eigene Fehler mit. Tritt ein Lichtsaum erst nach dem Upload in Ihren Shop oder Ihr CMS auf, vergleichen Sie die dekodierten Pixel von Master, Ihrem Export und der Vorschau der Plattform; oft ist die Skalierung oder Neukompression der Plattform die Ursache, nicht der Freisteller.

Wann eine andere Route das richtige Werkzeug ist

Für einen schlichten Freisteller ist Background Remover die günstigste Route dieser Tabelle und erhält die Größe der Quellfläche. Nutzen Sie eine andere Route, wenn Sie etwas brauchen, das er bewusst nicht anbietet.

Wenn ein generatives Modell ein PNG liefert, ist es dadurch nicht transparent: Ein PNG kann einen deckend weißen Hintergrund enthalten. Dekodieren Sie jedes Ergebnis mit demselben Skript. Wo exakte Produktpixel zählen (Etiketten, Logos, Verpackungstext), ziehen Sie die Extraktionsroute einer generativen Neuzeichnung vor.

Einen Batch durchlaufen lassen, ohne die Prüfenden zu überlasten

Der Modellaufruf ist günstig und schnell; die Prüfung ist der Engpass. Beginnen Sie mit einem Pilot aus etwa einem Dutzend Fotos mit geklärten Rechten, die den Katalog repräsentieren: ein sauberes festes Objekt, eines mit Henkel oder Öffnung, eines glänzend, eines mit feiner Kante, eines mit einem störenden Objekt. Der Pilot entscheidet, welche Kategorien eine leichte Prüfung durchlaufen und welche immer von einem Menschen angesehen werden.

• Senden Sie mit begrenzter Parallelität und führen Sie eine eigene Download-Warteschlange, damit ein langsamer Download nie eine erneute Extraktion auslöst. Wiederholen Sie einen fehlgeschlagenen Download gegen das vorhandene Ergebnis, solange sein Link gültig ist. Der Backpressure-Leitfaden behandelt den Aufbau der Warteschlange.
• Speichern Sie pro Quellrevision Ihre eigene Asset-ID, die Prüfsumme der Quelle, die Aufgaben-ID, den Ausgabeort und die Prüfentscheidung. Eine SKU allein genügt nicht: Ein Produkt hat mehrere Ansichten und Neuaufnahmen.
• Verstehen Sie „succeeded“ als „bereit zur Prüfung“, nie als „veröffentlichen“. Führen Sie das Skript automatisch aus und schicken Sie dann nur markierte und stichprobenartige Dateien an einen Menschen. Kategorien, die den Pilot bestehen (feste Objekte auf neutralem Hintergrund), können mit regelmäßigen Stichproben in eine leichtere Spur wechseln, um Drift zu erkennen; reflektierende, transparente und mehrdeutige Artikel bleiben bei voller Prüfung. Prüfen Sie Kampagnen-Hero-Bilder vor Nebenansichten statt in der Reihenfolge der Fertigstellung.
• Für Benachrichtigungen bei Abschluss siehe den Leitfaden Polling vs. Webhook für asynchrone Aufgaben; in beiden Fällen speist das Ergebnis denselben Prüfschritt.
• Halten Sie an, wenn Fehler dieselbe Ursache haben. Zehn verlorene Henkelöffnungen sind eine Information über die Quellbilder, nicht zehn Gründe für einen neuen Versuch.

Was es pro akzeptiertem Bild kostet

Hundert Freisteller kosten $0.48 und tausend kosten $4.80. Entscheidend sind die Ausgaben pro akzeptiertem Master. Als Planungsbeispiel: Ein Batch aus 100 ersten Freistellern plus 10 neu zugeschnittenen sind 110 × $0.0048 = $0.528; bestehen 95 die Prüfung, sind das etwa $0.0056 pro akzeptiertem Bild.

Die Prüfzeit kostet meist mehr als die API. Die nützlichen Hebel liegen vorgelagert: Wenn die meiste Prüfzeit in Glasflaschen fließt, spart ein besser ausgeleuchtetes Setup dafür mehr als jeder Preisunterschied. Ein abgeschlossener Freisteller, den Sie ablehnen, ist trotzdem eine abgeschlossene, berechnete Ausgabe; fehlgeschlagene und abgelaufene Aufgaben geben ihre Reservierung frei.

Quelle, Master und Exporte getrennt halten

Bewahren Sie das Quellfoto, das transparente PNG-Master und jede reduzierte Auslieferungskopie als getrennte Dateien auf, benannt nach dem, was sie sind (zum Beispiel <asset>-source, <asset>-cutout-master, <asset>-catalogue-cream), und halten Sie retuschierte Versionen von der unberührten API-Ausgabe getrennt, damit sich ein späterer Lichtsaum auf den Freisteller oder den Export zurückführen lässt. Speichern Sie die freigegebene Zielgröße beim jeweiligen Master, damit eine Freigabe in Kartengröße nicht mit einer in Hero-Größe verwechselt wird.

Protokollieren Sie jede Ablehnung unter genau einer Kategorie: falsches Motiv, verlorenes Merkmal, Saum, übrig gebliebenes Hintergrundfragment oder Exportfehler. Eine Zählung zählt nur, wenn sie etwas ändert: eine Zuschnittsregel, eine manuelle Spur für Glas, eine korrigierte Export-Voreinstellung. Geben Sie dem Fotografen konkrete Aufnahmeregeln („den ganzen Henkel sichtbar lassen; keine Geschenkbox hinter der Öffnung“, „dunklerer Hintergrund für helle Produkte“) statt „machen Sie es der KI leichter“.

Fragen

Gibt es eine kostenlose API zum Entfernen von Hintergründen?

Nicht für diesen Endpoint: Jede abgeschlossene Ausgabe kostet $0.0048, ein Pilot mit 100 Fotos also $0.48. Wenn kostenlos Pflicht ist, vermeidet das Selbsthosten eines Open-Source-Tools wie rembg Gebühren pro Bild, aber Betrieb und Feinabstimmung liegen dann bei Ihnen; die gehostete Route bietet einen stabilen Endpoint und planbare Kosten.

Macht das Speichern des Ergebnisses als PNG den Hintergrund transparent?

Nein. Ein PNG kann Alpha tragen, aber auch einen deckend weißen Hintergrund enthalten. Dekodieren Sie die Datei und lesen Sie den Alphakanal, prüfen Sie dann Kompositionen auf hellem und dunklem Hintergrund. Ein JPEG in .png umzubenennen, bringt nichts.

Kann ich vorgeben, den Henkel, die Haare oder den Schatten zu behalten?

Nicht bei dieser Aufgabe: Ihre Eingabe ist nur die Bild-URL. Schneiden Sie die Quelle zu, fotografieren Sie neu oder retuschieren Sie lokal. Wenn Sie ein promptgesteuertes Ergebnis wollen, nutzen Sie eine Bildbearbeitungsroute aus der Tabelle oben und prüfen Sie danach das Produkt und das Alpha.

Wie fange ich an?

Wählen Sie ein repräsentatives Produkt und ein Ziel. Senden Sie das Foto, dekodieren Sie das PNG, prüfen Sie die Kanten auf zwei Hintergründen, reduzieren Sie die freigegebene Ableitung auf eine Farbe und lassen Sie die Designerin sie im echten Layout öffnen. Führen Sie dann die schwierigeren Fälle Ihres Piloten aus und notieren Sie, welche eine Neuaufnahme oder eine manuelle Spur brauchen, bevor Sie den ganzen Katalog einplanen.

Einen Agent den Aufruf erledigen lassen

Setzen Sie einen Agent ein, wenn er die Eingaben vorbereiten und das Ergebnis zurückgeben soll, während Sie Preis und kreative Entscheidungen freigeben.

• CLI: Speichern Sie dasselbe Eingabeobjekt als input.json und verwenden Sie npx @spicyapi/cli tasks create --model spicyapi/background-remover-v1/edit --input-file input.json --wait. Die CLI lässt Sie den Preis bestätigen; behalten Sie die zurückgegebene Aufgaben-ID für die Wiederherstellung.
• MCP: Bitten Sie Ihren Assistenten, spicyapi_task_create für spicyapi/background-remover-v1/edit zu verwenden, danach spicyapi_task_wait. Der MCP-Server verlangt vor dem Erstellen eine Preisbestätigung.
• Skill: Installieren Sie ihn mit npx skills add spicyapi-ai/spicy-skill und bitten Sie dann $spicyapi, denselben Ablauf auszuführen und für Ihre Freigabe anzuhalten. Der Skill nutzt eine konfigurierte CLI- oder MCP-Verbindung.