API de remoção de objetos: crie uma máscara e baixe a imagem editada

Use spicyapi/object-eraser-v1/edit com image_url e um prompt curto, uma mask_url ou ambos. Em uma máscara, branco significa remover e preto significa manter, e as dimensões em pixels devem ser iguais às da imagem de origem. O preço é de US$ 0,03 por imagem de saída, não importa quantos objetos a requisição remova. O resultado mantém o tamanho original da tela e preenche a área selecionada com o conteúdo da cena ao redor.

Escolha entre prompt e máscara

Para um objeto inconfundível e com espaço ao redor, comece com uma descrição curta:

o copo de papel branco no chão ao lado da perna dianteira direita da cadeira

Use um substantivo, uma cor ou material visível e uma posição. "Deixe a cena limpa e premium" não identifica o que deve desaparecer. O prompt aceita de 1 a 1000 caracteres, mas uma descrição mais longa não seleciona com mais precisão.

Uma descrição que não corresponde a nada devolve a imagem sem alteração, e a tarefa ainda assim é concluída com sucesso. Compare a saída com a origem antes de tratá-la como uma remoção.

Ilustração com possíveis seleções. Todos os objetos marcados continuam presentes; não é uma saída da API.

Teste primeiro no Playground

1. Abra a página do Object Eraser, fique na aba Playground na visualização Form e entre com uma conta com saldo para executar.
2. Adicione a foto em Input image (JPG, PNG ou WebP, até 10 MB). Solte um arquivo, cole um link com Asset URL e Add URL, ou procure no computador.
3. Descreva o alvo em Prompt, ou adicione sua imagem em preto e branco em Mask, ou preencha os dois. O formulário exige pelo menos um deles.
4. Deixe Output format em PNG (JPEG e WebP geram arquivos menores) e execute. O preço é de US$ 0,03 por imagem.
5. Abra o resultado ao lado do original e da máscara e use a tabela de falhas abaixo se sobrar algo.

O painel Request body mostra o mesmo JSON que a API recebe, então um prompt ou uma máscara que funcione aqui pode ser copiado direto para o código. Se falhar aqui, corrija o prompt ou a máscara antes de escrever uma linha de código.

Faça a máscara sobre a imagem exata que você vai enviar

Se você já conhece a região (uma caixa de um detector ou uma seleção na interface), gere a máscara no código. O tamanho dela vem da origem, então sempre coincide:

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

Para formas irregulares em uma origem de 2400×1600, prepare em um editor de imagens uma máscara de 2400×1600:

1. Termine primeiro a rotação e o corte da origem e salve essa imagem de trabalho.
2. Adicione uma camada preta no tamanho total da tela e reduza a opacidade enquanto desenha, para o alvo continuar visível.
3. Pinte o copo de branco, incluindo a borda indesejada e a sombra de contato, com uma pequena margem onde houver espaço. A perna da cadeira fica preta.
4. Volte a camada à opacidade total e exporte-a sozinha como PNG opaco em preto e branco, não como foto escurecida nem com anotações coloridas.
5. Sobreponha a máscara exportada à imagem de trabalho e confira a região branca.

Proporções iguais não bastam: os dois arquivos precisam ter a mesma largura, altura, corte e orientação. Uma forma um pouco generosa funciona onde não há mais nada por perto. A máscara de exemplo da página do modelo, para uma prateleira na borda do enquadramento, é uma tela preta do tamanho da foto com um único retângulo branco liso sobre a prateleira.

Sombras e reflexos podem ficar fora da silhueta do objeto. Pinte um reflexo indesejado como uma região branca própria. Onde a sombra do copo se sobrepõe à sombra de apoio da cadeira, não pinte toda a mancha escura de branco, ou a cadeira pode acabar flutuando. A máscara marca o que será removido; ela não fornece o chão escondido nem a geometria do produto.

Faça remoções grandes ou sobrepostas em passadas separadas, montando cada máscara sobre a saída anterior já aceita. Dois objetos pequenos em uma requisição custam US$ 0,03; duas requisições separadas custam US$ 0,06. Mantenha os nomes de arquivo da máscara e da imagem em par, para que uma seleção antiga não edite em silêncio uma foto mais nova.

Depois, execute pelo código

Instale o SDK Python (pip install spicyapi), defina SPICY_API_KEY no ambiente do seu servidor e execute a requisição abaixo. Ela usa a foto de exemplo da página do modelo, então funciona como está. Arquivos do seu computador passam por client.upload_file e voltam como um endereço spicy://. Para uma máscara, adicione "mask_url" com seu próprio arquivo, do mesmo tamanho em pixels que a 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 now

Uploads, criação, espera, download, novas tentativas e códigos de erro estão no guia de tarefas e na referência do SDK Python. Os arquivos gerados são mantidos por no máximo 14 dias, então copie o resultado para o seu próprio armazenamento.

Ou deixe um agente executar

Quando um assistente deve fazer a edição, as três ferramentas oficiais mostram o preço e pedem sua confirmação antes de uma chamada paga.

• CLI. Envie a foto e a máscara e depois crie a tarefa:

``bash spicyapi files upload photo.jpg spicyapi tasks create --model spicyapi/object-eraser-v1/edit --input-file input.json --wait ``

Coloque os endereços spicy:// retornados em input.json como image_url e mask_url. Veja a documentação da CLI; npx @spicyapi/cli funciona sem instalação.

• Servidor MCP. Adicione o servidor MCP ao seu assistente e peça: "Remova o copo de papel branco desta foto com o Object Eraser; o arquivo está em /path/to/photo.jpg". Ele envia o arquivo com spicyapi_upload_file, chama spicyapi_task_create, que para para você confirmar o preço, e depois spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill instala o Agent Skill, com o qual um assistente de código lê o esquema atual do modelo em vez de adivinhar os campos.

Corrija a falha específica que você vê

Abra erased.png ao lado do original e da máscara. Confira primeiro onde a seleção encontra o conteúdo mantido e depois o centro do preenchimento.

Ilustração sobre a inspeção de sombras e reflexos. Não mostra uma remoção concluída.

O modelo reconstrói o fundo escondido; ele não consegue revelar o que realmente havia atrás do objeto. Em uma página de produto, não aceite uma junção de cadeira inventada nem uma costura de estofado alterada só porque o chão parece mais limpo. Refaça a foto quando o objeto removido esconder um detalhe que o anúncio precisa mostrar com exatidão.

A SpicyAPI não executa nenhum verificador de segurança neste modelo; o próprio modelo decide o que devolve.

Guarde a origem e a máscara junto com a saída aceita e adicione outra passada apenas para um objeto específico que restar. A aba Examples da página do modelo mostra resultados reais de antes e depois.