API de remoção de fundo: entregue PNGs de produto transparentes

Você tem algumas centenas de fotos de produto sobre mesas cinzentas e parapeitos de janela, e a loja, o marketplace ou o designer quer cada uma como PNG transparente. O SpicyAPI Background Remover faz isso em uma chamada: você envia a URL de uma foto e recebe o sujeito principal em um PNG transparente com a largura e a altura originais. O trabalho que sobra é seu: confirmar que o arquivo realmente tem alfa, conferir as bordas nos fundos em que ele será usado e exportar as cópias achatadas que cada destino pede.

Experimente primeiro no Playground

Abra o Playground do background-remover-v1. Solte uma foto de produto em Input image, confira o preço e clique em Run model. Inspecione o resultado transparente sobre fundos claros e escuros antes de usar a mesma foto no código.

O que o endpoint recebe e devolve

A saída mantém as dimensões da tela de origem, então você pode posicionar o recorte sobre um fundo substituto sem redimensionar. Use o canal alfa devolvido como limite do recorte; manter a mesma tela não garante que cada borda ou cor do primeiro plano permaneça inalterada. Os detalhes estão na página do modelo Background Remover.

Veja primeiro um resultado real

O exemplo da própria página do modelo é um frasco conta-gotas fosco sobre um fundo cinza de estúdio, com 1024 × 1536 pixels. São os arquivos de antes e depois dessa página; o «depois» aparece aqui sobre o fundo da página.

Rodar o script de verificação das próximas seções nesse par dá os números de um bom resultado: a saída tem canal alfa, o tamanho bate com o da origem, cerca de 78% dos pixels estão totalmente transparentes, cerca de 22% são sólidos e apenas cerca de 0,35% são pixels de borda semitransparentes. A caixa do sujeito mede 335 × 1.234 pixels. Composto sobre um fundo azul-marinho escuro, a ponta do conta-gotas, o colar escovado e os ombros de vidro fosco não têm nenhum halo claro.

Faça a chamada

Instale spicyapi e pillow com python -m pip install spicyapi pillow. Defina SPICY_API_KEY e IMAGE_URL com a URL direta da sua imagem de origem e execute este exemplo. Ele pede que você confirme o preço, cria a tarefa, espera por ela, salva o recorte e grava prévias sobre fundo claro e escuro.

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

Para repetir a mesma requisição depois de perder a resposta, reutilize a chave de idempotência dela em vez de criar uma nova (referência de idempotência). Para upload de arquivos locais, veja o SDK Python e a documentação de mídia.

Verifique a transparência decodificando o arquivo

Uma prévia branca não prova nada. Pode ser um recorte genuíno sobre uma página branca, uma imagem opaca com fundo branco ou um padrão quadriculado pintado nos pixels. Decodifique o arquivo e leia o canal alfa dele. A especificação PNG define como o alfa é armazenado; na prática, você precisa saber se alguns pixels podem ser transparentes depois da decodificação, não o que o nome do arquivo diz.

O exemplo informa como o alfa está distribuído e grava composições sobre creme e azul-marinho escuro para revisão com o Pillow. Compare as dimensões que ele informa com as da sua origem.

Atenção aos limiares. Contar apenas o alfa 255 como opaco engana: na saída do frasco conta-gotas, cerca de 14% dos pixels ficam entre os alfas 1 e 254, mas quase todos são 254, que visualmente é sólido. Tratar o alfa até 8 como transparente e a partir de 247 como sólido deixa a fração suave para o que realmente importa: bordas suavizadas, cabelo e material genuinamente translúcido.

Como ler o relatório:

• A ausência de canal alfa, ou um alpha_min_max de (255, 255), significa que não há transparência: investigue o pipeline antes de revisar as bordas.
• Um clear_fraction perto de 0 em uma foto que tinha fundo, ou um solid_fraction perto de 0, significa que o sujeito se perdeu ou que o resultado é uma névoa.
• Uma diferença de tamanho geralmente indica uma origem girada por EXIF ou um redimensionamento no seu próprio código, já que o endpoint preserva as dimensões.
• Um soft_fraction alto é normal para vidro, tecido e cabelo e um sinal de alerta para uma caneca fosca. Defina os limiares por categoria de produto depois de ver um conjunto-piloto, não um único número global.
• Uma caixa do sujeito que encosta na borda da tela em uma foto que você recortou com folga sugere que um segundo objeto foi mantido.

Prepare a foto sem alterar o produto

Decida o que conta como produto antes de fotografar ou recortar: um laço, a embalagem e uma sombra de contato estão dentro ou fora, e a ferramenta não consegue adivinhar um briefing que nunca foi escrito. Não repinte uma borda lascada nem invente um logotipo ausente; um defeito que o anúncio precisa mostrar fica na foto.

• Recorte para remover objetos concorrentes, mas deixe margem em torno de cada extremidade, para que uma alça ou tira não seja cortada antes que a API a veja.
• Objetos sobrepostos não se resolvem recortando, porque o limite oculto precisa ser adivinhado. Refaça a foto e encaminhe sobreposições, suportes de exposição transparentes e sujeitos cortados para uma faixa de exceções, para que não travem o lote normal.
• Envie o arquivo mais limpo. Reexportações repetidas em JPEG deixam artefatos de blocos exatamente onde a borda precisa de detalhe; mantenha uma cópia de trabalho sem perdas. Converta perfis de cor de forma deliberada, porque uma conversão descuidada muda a cor do produto antes de alguém revisar o recorte.

Revise a borda onde a imagem será usada

Coloque o recorte sobre o fundo de destino real, não só sobre a página em que você o revisa. Um recorte que parece limpo sobre creme pode mostrar uma borda pálida sobre azul-marinho escuro; essa borda é cor do fundo de origem que ficou em pixels parcialmente transparentes. Confira no tamanho de entrega, para ver se um defeito importa, e a 100%, para ver o formato dele. As duas composições do script usam creme e azul-marinho escuro; troque pelas cores da sua marca.

Olhe as regiões pelas quais esse tipo de produto é reconhecido, não cada pixel por igual: o interior da alça de uma caneca, a borda e a base, cadarços e solas, cerdas, a ponta do conta-gotas. Compare origem, alfa e composição na mesma escala e no mesmo enquadramento. Ao rejeitar um arquivo, nomeie a característica perdida e o destino («abertura da alça preenchida na composição escura»), para que a próxima pessoa saiba se deve recortar, retocar ou refotografar.

Três situações pedem uma decisão, não uma nova tentativa:

• Furos dentro da silhueta. A abertura de uma alça ou o vão entre as barras de uma cadeira pertencem ao fundo. Uma verificação só do contorno pode parecer correta mesmo com o furo preenchido. Confira na composição escura.
• Sombras. Uma sombra de contato assenta o produto; uma sombra projetada longa arrasta a textura do fundo para dentro do recorte. Decida se o master mantém uma e se o layout vai desenhar a sua. Se você adicionar a sua, suavize ou remova a sombra que já está na origem para que duas não entrem em conflito.
• Vidro e material translúcido. A cor de uma garrafa inclui a luz do fundo que a atravessa, então nenhum recorte consegue dar uma garrafa fisicamente correta sobre qualquer fundo novo; um reflexo pálido de estúdio que parece natural sobre branco pode parecer errado sobre escuro. Mantenha o alfa parcial em plástico e tecido translúcidos em vez de limiarizá-lo para 0 ou 255, e não erode a máscara inteira para remover um halo: você afina o produto e perde detalhes finos. Retoque localmente em uma cópia.

Corrija a falha na etapa que a causou

Classifique antes de executar de novo. Uma chamada repetida custa dinheiro e, na maioria desses casos, não muda nada.

Não há prompt para orientar a ferramenta, então as alavancas são a foto de entrada e o que você faz depois da chamada. Se uma categoria continua falhando, mude a forma de fotografá-la em vez de repetir requisições.

Achate para destinos que exigem fundo sólido

Marketplaces costumam pedir um JPEG sobre branco. O JPEG não tem alfa, então exportar o master para JPEG preenche a área transparente com uma cor padrão que ninguém aprovou. Achate sobre uma cor escolhida, mantenha o PNG como master e redimensione de forma uniforme (nunca estique largura e altura de forma independente). O light.jpg que o script grava é exatamente esta etapa sobre creme; para branco, troque a cor no laço ou exporte um JPEG achatado separado no seu editor de imagens. Confira o arquivo plano, não só o master: reamostragem, conversão de cor e compressão acrescentam seus próprios defeitos. Se um halo aparecer só depois do upload para a sua loja ou CMS, compare os pixels decodificados do master, da sua exportação e da miniatura da plataforma; muitas vezes a causa é o redimensionamento ou a recompressão da plataforma, não o recorte.

Quando outra rota é a ferramenta certa

Para um recorte simples, o Background Remover é a rota de menor preço desta tabela e preserva o tamanho da tela de origem. Use outra rota quando precisar de algo que ele deliberadamente não oferece.

Se um modelo generativo devolve um PNG, isso não o torna transparente: um PNG pode ter um fundo branco opaco. Decodifique cada resultado com o mesmo script. Onde os pixels exatos do produto importam (rótulos, logotipos, texto da embalagem), prefira a rota de extração a um redesenho generativo.

Rode um lote sem afogar os revisores

A chamada ao modelo é barata e rápida; a revisão é o gargalo. Comece com um piloto de cerca de uma dúzia de fotos com direitos liberados que representem o catálogo: um objeto sólido limpo, um com alça ou abertura, um brilhante, um com borda fina, um com um objeto concorrente. O piloto decide quais categorias passam por uma revisão leve e quais sempre vão para uma pessoa.

• Envie com concorrência limitada e mantenha uma fila de download separada, para que um download lento nunca dispare uma extração repetida. Repita um download que falhou contra o resultado existente enquanto o link dele for válido. O guia de contrapressão trata do desenho da fila.
• Guarde, por revisão de origem, o seu próprio ID de ativo, o checksum da origem, o ID da tarefa, o local da saída e a decisão de revisão. Só o SKU não basta: um produto tem vários ângulos e refotografias.
• Trate «succeeded» como «pronto para inspeção», nunca como «publicar». Rode o script automaticamente e envie a uma pessoa só os arquivos sinalizados e uma amostra. Categorias que passam no piloto (objetos sólidos em fundos neutros) podem ir para uma faixa mais leve, com amostragem periódica para detectar deriva; itens reflexivos, transparentes e ambíguos continuam em revisão completa. Revise as imagens principais de campanha antes dos ângulos secundários, em vez de seguir a ordem de conclusão.
• Para notificações de conclusão, veja o guia de polling vs Webhook para tarefas assíncronas; de qualquer forma, o resultado alimenta a mesma etapa de inspeção.
• Pause quando as falhas tiverem a mesma causa. Dez aberturas de alça perdidas são informação sobre o conjunto de origem, não dez motivos para tentar de novo.

Quanto custa por imagem aceita

Cem recortes custam $0,48 e mil custam $4,80. O número que importa é o gasto por master aceito. Como exemplo de planejamento, um lote de 100 primeiros recortes mais 10 recortados de novo dá 110 × $0,0048 = $0,528; se 95 passarem na revisão, são cerca de $0,0056 por imagem aceita.

O tempo de revisão geralmente custa mais do que a API. As alavancas úteis ficam a montante: se a maior parte do tempo de revisão vai para garrafas de vidro, uma iluminação melhor para elas economiza mais do que qualquer diferença de preço. Um recorte concluído que você rejeita continua sendo uma saída concluída e cobrada; tarefas que falham ou expiram liberam a retenção.

Mantenha origem, master e exportações separados

Mantenha a foto de origem, o master PNG transparente e cada cópia de entrega achatada como arquivos separados, nomeados pelo que são (por exemplo <asset>-source, <asset>-cutout-master, <asset>-catalogue-cream), e mantenha as versões retocadas separadas da saída intacta da API, para que um halo posterior possa ser atribuído ao recorte ou à exportação. Guarde com cada master o tamanho de destino aprovado, para que uma aprovação em tamanho de card não seja confundida com uma em tamanho de imagem principal.

Registre cada rejeição em uma única categoria: sujeito errado, característica perdida, franja, fragmento de fundo remanescente ou defeito de exportação. Uma contagem só importa quando muda algo: uma regra de recorte, uma faixa manual para vidro, uma predefinição de exportação corrigida. Dê ao fotógrafo regras de captura concretas («mantenha a alça inteira visível; sem caixa de presente atrás da abertura», «fundo mais escuro para produtos claros») em vez de «facilite para a IA».

Perguntas

Existe uma API gratuita para remover fundo?

Não para este endpoint: cada saída concluída custa $0,0048, então um piloto de 100 fotos custa $0,48. Se gratuito for requisito, hospedar por conta própria um removedor de código aberto como o rembg evita tarifas por imagem, mas aí você o opera e o ajusta; a rota hospedada oferece um endpoint estável e custo previsível.

Salvar o resultado como PNG torna o fundo transparente?

Não. Um PNG pode ter alfa, mas também pode conter um fundo branco opaco. Decodifique o arquivo e leia o canal alfa, depois revise composições sobre fundo claro e escuro. Renomear um JPEG para .png não acrescenta nada.

Posso pedir que mantenha a alça, o cabelo ou a sombra?

Não nesta tarefa: a entrada dela é só a URL da imagem. Recorte a origem, refotografe ou retoque localmente. Se quiser um resultado guiado por prompt, use uma rota de edição de imagem da tabela acima e verifique depois o produto e o alfa.

Como devo começar?

Escolha um produto representativo e um destino. Envie a foto, decodifique o PNG, revise as bordas sobre dois fundos, achate a derivada aprovada e peça ao designer que a abra no layout real. Depois rode os casos mais difíceis do seu conjunto-piloto e anote quais precisam de refotografia ou de uma faixa manual antes de agendar o catálogo inteiro.

Deixe um Agent cuidar da chamada

Use um Agent quando quiser que ele prepare as entradas e devolva o resultado enquanto você aprova o preço e as decisões criativas.

• CLI: com o mesmo objeto de entrada salvo como input.json, use npx @spicyapi/cli tasks create --model spicyapi/background-remover-v1/edit --input-file input.json --wait. A CLI pede a confirmação do preço; guarde o ID da tarefa devolvido para recuperação.
• MCP: peça ao seu assistente que use spicyapi_task_create para spicyapi/background-remover-v1/edit e depois spicyapi_task_wait. O servidor MCP solicita a confirmação do preço antes da criação.
• Skill: instale com npx skills add spicyapi-ai/spicy-skill e peça então a $spicyapi que execute o mesmo fluxo de trabalho e pare para a sua aprovação. A Skill usa uma conexão CLI ou MCP já configurada.