API de détourage : livrer des PNG de produits transparents

Vous avez quelques centaines de photos produit prises sur des tables grises et des rebords de fenêtre, et la boutique, la place de marché ou le designer veut chacune en PNG transparent. SpicyAPI Background Remover le fait en un appel : vous envoyez l’URL d’une photo et vous récupérez le sujet principal sur un PNG transparent, à la largeur et à la hauteur d’origine. Le travail restant est le vôtre : confirmer que le fichier a bien un canal alpha, vérifier les contours sur les fonds où il sera placé et exporter les copies aplaties que chaque destination demande.

Essayez d’abord dans le Playground

Ouvrez le Playground background-remover-v1. Déposez une photo produit dans Input image, vérifiez le prix et appuyez sur Run model. Inspectez le résultat transparent sur des fonds clairs et sombres avant d’utiliser la même photo dans le code.

Ce que l’endpoint reçoit et renvoie

La sortie conserve les dimensions du canevas source ; vous pouvez donc placer le détourage sur un nouveau fond sans redimensionner. Utilisez le canal alpha renvoyé comme limite du détourage ; conserver le même canevas ne garantit pas que chaque contour ou couleur du premier plan reste inchangé. Les détails figurent sur la page du modèle Background Remover.

Voyez d’abord un vrai résultat

L’exemple de la page du modèle est un flacon compte-gouttes dépoli sur un fond de studio gris, de 1024 × 1536 pixels. Voici les fichiers avant et après de cette page ; l’« après » est affiché ici sur le fond de la page.

Exécuter sur cette paire le script de contrôle des sections suivantes donne les chiffres d’un bon résultat : la sortie a un canal alpha, la taille correspond à la source, environ 78 % des pixels sont totalement transparents, environ 22 % sont pleins et seulement environ 0.35 % sont des pixels de contour semi-transparents. La boîte du sujet mesure 335 × 1 234 pixels. Composé sur un fond bleu marine foncé, l’embout du compte-gouttes, la bague brossée et les épaules en verre dépoli n’ont aucune frange claire.

Faites l’appel

Installez spicyapi et pillow avec python -m pip install spicyapi pillow. Définissez SPICY_API_KEY et IMAGE_URL avec l’URL directe de votre image source, puis exécutez cet exemple. Il vous demande de confirmer le prix, crée la tâche, l’attend, enregistre le détourage et écrit des aperçus sur fond clair et sombre.

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

Pour réessayer la même requête après une réponse perdue, réutilisez sa clé d’idempotence au lieu d’en créer une nouvelle (référence sur l’idempotence). Pour l’envoi de fichiers locaux, consultez le SDK Python et la documentation sur les médias.

Vérifiez la transparence en décodant le fichier

Un aperçu blanc ne prouve rien. Ce peut être un vrai détourage sur une page blanche, une image opaque à fond blanc, ou un damier peint dans les pixels. Décodez le fichier et lisez son canal alpha. La spécification PNG définit la façon dont l’alpha est stocké ; en pratique, ce qu’il vous faut savoir, c’est si certains pixels peuvent être transparents après décodage, pas ce que dit le nom du fichier.

L’exemple indique comment l’alpha est réparti et écrit des composites crème et bleu marine foncé à examiner avec Pillow. Comparez les dimensions qu’il indique à celles de votre source.

Soyez attentif aux seuils. Ne compter comme opaque que l’alpha 255 est trompeur : sur la sortie du flacon compte-gouttes, environ 14 % des pixels ont un alpha de 1 à 254, mais presque tous valent 254, ce qui est visuellement plein. En considérant l’alpha jusqu’à 8 comme transparent et à partir de 247 comme plein, la fraction douce reste pour ce qui vous intéresse vraiment : contours lissés, cheveux et matière réellement translucide.

Comment lire le rapport :

• Un canal alpha absent, ou un alpha_min_max de (255, 255), signifie aucune transparence : examinez la chaîne de traitement avant de vérifier les contours.
• Un clear_fraction proche de 0 sur une photo qui avait un fond, ou un solid_fraction proche de 0, signifie que le sujet a été perdu ou que le résultat est un voile.
• Une taille différente indique généralement une source pivotée par EXIF ou un redimensionnement dans votre propre code, puisque l’endpoint préserve les dimensions.
• Un soft_fraction élevé est normal pour le verre, le tissu et les cheveux, et un signal d’alerte pour une tasse mate. Fixez les seuils par catégorie de produit après avoir examiné un lot pilote, pas un seul chiffre global.
• Une boîte du sujet qui touche le bord du canevas sur une photo que vous avez recadrée largement laisse penser qu’un second objet a été conservé.

Préparez la photo sans modifier le produit

Décidez de ce qui compte comme produit avant de photographier ou de recadrer : un ruban, l’emballage et une ombre de contact sont soit dedans, soit dehors, et l’outil ne peut pas deviner une consigne qui n’a jamais été écrite. Ne retouchez pas un bord ébréché et n’inventez pas un logo manquant ; un défaut que l’annonce doit montrer reste sur la photo.

• Recadrez pour retirer les objets concurrents, mais laissez de la marge autour de chaque extrémité, afin qu’une anse ou une sangle ne soit pas coupée avant que l’API la voie.
• Des objets qui se chevauchent ne se règlent pas par le recadrage, car la limite cachée doit être devinée. Refaites la prise de vue et dirigez les chevauchements, les supports d’exposition transparents et les sujets coupés vers une voie d’exception pour qu’ils n’encombrent pas le lot normal.
• Envoyez le fichier le plus propre. Les réexportations JPEG répétées laissent des artefacts de blocs exactement là où le contour a besoin de détail ; gardez une copie de travail sans perte. Convertissez les profils colorimétriques de façon délibérée, car une conversion négligée change la couleur du produit avant que quiconque ait examiné le détourage.

Examinez le contour là où l’image sera utilisée

Placez le détourage sur le vrai fond de destination, pas seulement sur la page où vous le contrôlez. Un détourage propre sur crème peut montrer un liséré pâle sur bleu marine foncé ; ce liséré est de la couleur du fond source restée dans des pixels partiellement transparents. Vérifiez à la taille de livraison, pour voir si un défaut compte, et à 100 %, pour voir sa forme. Les deux composites du script utilisent crème et bleu marine foncé ; remplacez-les par les couleurs de votre marque.

Regardez les zones où ce type de produit se reconnaît, et non chaque pixel à égalité : l’intérieur de l’anse d’une tasse, le bord et le pied, les lacets et les semelles, les poils, l’embout du compte-gouttes. Comparez source, alpha et composite à la même échelle et sur le même cadrage. Lorsque vous rejetez un fichier, nommez la caractéristique perdue et la destination (« ouverture de l’anse remplie sur le composite sombre »), pour que la personne suivante sache s’il faut recadrer, retoucher ou refaire la prise de vue.

Trois situations demandent une décision plutôt qu’un nouvel essai :

• Trous à l’intérieur de la silhouette. L’ouverture d’une anse ou l’espace entre les barreaux d’une chaise appartiennent au fond. Un contrôle limité au contour peut sembler correct alors que le trou est rempli. Vérifiez-le sur le composite sombre.
• Ombres. Une ombre de contact ancre un produit ; une longue ombre portée entraîne la texture du fond dans le détourage. Décidez si le master en conserve une et si la mise en page dessinera la sienne. Si vous ajoutez la vôtre, adoucissez ou supprimez l’ombre déjà présente dans la source pour que deux ombres ne se contredisent pas.
• Verre et matière translucide. La couleur d’une bouteille inclut la lumière du fond qui la traverse ; aucun détourage ne peut donc fournir une bouteille physiquement juste sur tous les nouveaux fonds. Un reflet de studio pâle qui paraît naturel sur du blanc peut sembler faux sur du sombre. Conservez l’alpha partiel pour le plastique et le tissu translucides au lieu de le seuiller à 0 ou 255, et n’érodez pas tout le masque pour supprimer un halo : vous amincissez le produit et perdez des détails fins. Retouchez localement sur une copie.

Corrigez l’échec à l’étape qui l’a causé

Classez-le avant de relancer. Un appel répété coûte de l’argent et, dans la plupart de ces cas, ne change rien.

Aucun prompt ne permet de guider l’outil ; les leviers sont donc la photo d’entrée et ce que vous faites après l’appel. Si une catégorie échoue sans cesse, changez la façon de la photographier au lieu de répéter les requêtes.

Aplatissez pour les destinations qui exigent un fond plein

Les places de marché demandent souvent un JPEG sur blanc. Le JPEG n’a pas d’alpha ; exporter le master en JPEG remplit donc la zone transparente avec une couleur par défaut que personne n’a approuvée. Aplatissez sur une couleur choisie, gardez le PNG comme master et redimensionnez uniformément (n’étirez jamais la largeur et la hauteur indépendamment). Le light.jpg que le script écrit correspond exactement à cette étape sur crème ; pour du blanc, changez la couleur dans la boucle, ou exportez un JPEG aplati à part depuis votre éditeur d’images. Vérifiez le fichier à plat, pas seulement le master : le rééchantillonnage, la conversion colorimétrique et la compression ajoutent leurs propres défauts. Si un halo n’apparaît qu’après l’envoi vers votre boutique ou votre CMS, comparez les pixels décodés du master, de votre export et de la miniature de la plateforme ; la cause est souvent le redimensionnement ou la recompression de la plateforme, pas le détourage.

Quand une autre voie est le bon outil

Pour un détourage simple, Background Remover est la voie la moins chère de ce tableau et préserve la taille du canevas source. Utilisez une autre voie lorsque vous avez besoin de ce qu’il ne propose délibérément pas.

Si un modèle génératif renvoie un PNG, cela ne le rend pas transparent : un PNG peut contenir un fond blanc opaque. Décodez chaque résultat avec le même script. Là où les pixels exacts du produit comptent (étiquettes, logos, texte de l’emballage), préférez la voie d’extraction à un redessin génératif.

Traitez un lot sans noyer les relecteurs

L’appel au modèle est peu coûteux et rapide ; la relecture est le goulot d’étranglement. Commencez par un pilote d’environ une douzaine de photos libres de droits qui représentent le catalogue : un objet plein et net, un avec une anse ou une ouverture, un brillant, un avec un contour fin, un avec un objet concurrent. Le pilote décide quelles catégories passent par une relecture légère et lesquelles passent toujours par un humain.

• Soumettez avec une concurrence bornée et gardez une file de téléchargement séparée, pour qu’un téléchargement lent ne déclenche jamais une nouvelle extraction. Réessayez un téléchargement échoué sur le résultat existant tant que son lien est valide. Le guide sur la contre-pression décrit la conception de la file.
• Conservez par révision de source votre propre ID d’asset, la somme de contrôle de la source, l’ID de tâche, l’emplacement de sortie et la décision de relecture. Un SKU seul ne suffit pas : un produit a plusieurs angles et des reprises de prise de vue.
• Considérez « succeeded » comme « prêt à inspecter », jamais comme « publier ». Exécutez le script automatiquement, puis ne confiez à une personne que les fichiers signalés et un échantillon. Les catégories qui passent le pilote (objets pleins sur fonds neutres) peuvent passer dans une voie plus légère avec un échantillonnage périodique pour détecter la dérive ; les articles réfléchissants, transparents et ambigus restent en relecture complète. Relisez les visuels principaux de campagne avant les angles secondaires, plutôt que dans l’ordre d’achèvement.
• Pour les notifications de fin, voir le guide polling vs Webhook pour les tâches asynchrones ; dans les deux cas, le résultat alimente la même étape d’inspection.
• Faites une pause lorsque les échecs ont une cause commune. Dix ouvertures d’anse perdues sont une information sur le lot de sources, pas dix raisons de réessayer.

Ce que coûte une image acceptée

Cent détourages coûtent $0.48 et mille coûtent $4.80. Le chiffre qui compte est la dépense par master accepté. À titre d’exemple de planification, un lot de 100 premiers détourages plus 10 recadrés de nouveau fait 110 × $0.0048 = $0.528 ; si 95 passent la relecture, cela fait environ $0.0056 par image acceptée.

Le temps de relecture coûte généralement plus cher que l’API. Les leviers utiles sont en amont : si l’essentiel du temps de relecture est consacré aux bouteilles en verre, un meilleur éclairage pour elles économise plus que n’importe quelle différence de prix. Un détourage terminé que vous rejetez reste une sortie terminée et facturée ; les tâches échouées et expirées libèrent leur blocage.

Séparez la source, le master et les exports

Gardez la photo source, le master PNG transparent et chaque copie de livraison aplatie comme des fichiers distincts, nommés d’après ce qu’ils sont (par exemple <asset>-source, <asset>-cutout-master, <asset>-catalogue-cream), et tenez les versions retouchées à l’écart de la sortie brute de l’API, afin qu’un halo ultérieur puisse être attribué au détourage ou à l’export. Conservez avec chaque master la taille de destination approuvée, pour qu’une validation à la taille d’une vignette ne soit pas confondue avec une validation à la taille d’un visuel principal.

Consignez chaque rejet sous une seule catégorie : mauvais sujet, caractéristique perdue, frange, fragment de fond résiduel ou défaut d’export. Un décompte n’a d’intérêt que s’il change quelque chose : une règle de recadrage, une voie manuelle pour le verre, un préréglage d’export corrigé. Donnez au photographe des règles de prise de vue concrètes (« garder toute l’anse visible ; pas de boîte cadeau derrière l’ouverture », « fond plus sombre pour les produits clairs ») plutôt que « rendez ça plus facile pour l’IA ».

Questions

Existe-t-il une API gratuite de suppression d’arrière-plan ?

Pas pour cet endpoint : chaque sortie terminée coûte $0.0048, donc un pilote de 100 photos coûte $0.48. Si la gratuité est une exigence, auto-héberger un outil open source comme rembg évite les frais par image, mais vous l’exploitez et le réglez alors vous-même ; la voie hébergée vous apporte un endpoint stable et un coût prévisible.

Enregistrer le résultat en PNG rend-il l’arrière-plan transparent ?

Non. Un PNG peut porter de l’alpha, mais il peut aussi contenir un fond blanc opaque. Décodez le fichier et lisez le canal alpha, puis examinez des composites sur fond clair et sombre. Renommer un JPEG en .png n’apporte rien.

Puis-je lui demander de garder l’anse, les cheveux ou l’ombre ?

Pas avec cette tâche : son entrée est uniquement l’URL de l’image. Recadrez la source, refaites la prise de vue ou retouchez localement. Si vous voulez un résultat piloté par prompt, utilisez une voie de retouche d’image du tableau ci-dessus et vérifiez ensuite le produit et l’alpha.

Comment commencer ?

Choisissez un produit représentatif et une destination. Envoyez la photo, décodez le PNG, examinez les contours sur deux fonds, aplatissez la version dérivée approuvée et demandez au designer de l’ouvrir dans la vraie mise en page. Exécutez ensuite les cas plus difficiles de votre lot pilote et notez lesquels demandent une nouvelle prise de vue ou une voie manuelle avant de planifier tout le catalogue.

Laissez un Agent s’occuper de l’appel

Utilisez un Agent lorsque vous voulez qu’il prépare les entrées et renvoie le résultat pendant que vous approuvez le prix et les choix créatifs.

• CLI : avec le même objet d’entrée enregistré sous input.json, utilisez npx @spicyapi/cli tasks create --model spicyapi/background-remover-v1/edit --input-file input.json --wait. La CLI fait confirmer le prix ; gardez l’ID de tâche renvoyé pour la reprise.
• MCP : demandez à votre assistant d’utiliser spicyapi_task_create pour spicyapi/background-remover-v1/edit, puis spicyapi_task_wait. Le serveur MCP demande une confirmation du prix avant la création.
• Skill : installez-le avec npx skills add spicyapi-ai/spicy-skill, puis demandez à $spicyapi d’exécuter le même flux de travail et de s’arrêter pour obtenir votre approbation. Le Skill utilise une connexion CLI ou MCP déjà configurée.