Como remover o fundo de imagens com uma API

Remover um fundo à mão leva alguns minutos por foto. Fazer isso em cada upload de produto, foto de perfil ou thumbnail do seu app exige uma API para remover fundo: entra uma requisição HTTP, sai um recorte pronto.

Este guia mostra como integrar uma do jeito certo. Você terá código funcional em cURL, Python e JavaScript, as opções de saída que vale conhecer, como lidar com imagens lentas e jobs em massa, e como repetir requisições sem pagar duas vezes. Os exemplos usam o removebackground.dev, nosso produto irmão, mas os padrões valem para qualquer provedor.

Como funciona uma API para remover fundo

Você envia uma imagem, o provedor executa um modelo de segmentação que separa o objeto principal do fundo, e você recebe uma nova imagem. O núcleo do resultado é um canal alfa: um valor por pixel que diz quanto de cada pixel pertence ao objeto principal. Pixels totalmente opacos são o objeto, pixels totalmente transparentes são fundo, e os valores intermediários cuidam de bordas suaves como cabelo, pelos e vidro.

A partir dessa máscara, a API pode devolver várias coisas:

• Um recorte transparente, geralmente um PNG ou WebP sem o fundo
• O objeto sobre uma cor sólida, achatado em um JPG para marketplaces que exigem fundo branco
• A própria máscara, uma imagem em tons de cinza que você pode usar no seu próprio pipeline de composição
• Uma versão recortada ou redimensionada, ajustada ao objeto e a um tamanho exato

A requisição é a parte fácil. Uma integração em produção também precisa lidar com imagens que demoram mais que o normal, lotes grandes, limites de taxa, retries e manter a chave de API longe dos usuários.

O que avaliar em uma API para remover fundo

Antes de escrever código, confira estes pontos com suas próprias imagens e seu tráfego.

Passo 1: Crie uma chave de API

Cadastre-se no removebackground.dev e crie uma chave na página da sua conta. Contas novas ganham 50 créditos grátis, o suficiente para rodar os exemplos abaixo e testar com suas próprias imagens.

Guarde a chave em uma variável de ambiente no seu servidor:

export REMOVEBG_API_KEY="your_api_key"

Toda chamada envia a chave no header x-api-key, e toda chamada gasta os créditos daquela conta. Crie uma chave separada por app ou ambiente para poder revogar uma sem quebrar as outras.

Passo 2: Remova um fundo com cURL

O endpoint em tempo real é POST https://removebackground.dev/v1/remove. O teste mais rápido é um upload de arquivo:

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@photo.jpg' \
  -o photo-no-bg.png

A maioria das imagens avulsas volta pronta na mesma resposta, normalmente em poucos segundos, como PNG transparente em resolução total.

O endpoint aceita a imagem de quatro formas. Envie uma delas:

Se uma requisição trouxer várias, image_file vence, depois image_file_b64, depois image_url e por fim o corpo bruto. As opções podem ser enviadas como campos de formulário, chaves JSON ou valores de query string.

Um ponto de atenção: -o salva o corpo qualquer que seja o status. Se a chave estiver errada ou a imagem for inválida, seu "PNG" na verdade é um erro em JSON. Verifique o código de status antes de confiar no arquivo.

Passo 3: Trate 200, 202 e erros em Python

Uma API para remover fundo não pode prometer que toda imagem termine dentro de uma única requisição HTTP. Quando a fila está mais cheia que o normal e uma imagem leva mais de uns 55 segundos, o removebackground.dev responde 202 Accepted com um id de job em vez da imagem. O job continua rodando, e você busca o resultado com o id.

A regra principal: nunca reenvie a imagem depois de um 202. Isso inicia um segundo job e pode custar um segundo crédito. Aqui está uma versão completa em Python que envia a imagem uma única vez e só repete as chamadas seguras:

import os
import time
import uuid
import requests

API = "https://removebackground.dev"
KEY = os.environ["REMOVEBG_API_KEY"]  # keep the key on your server
EXT = {"image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp"}


def save(res, stem):
    """Save an image response with the right extension; raise on anything else."""
    mime = res.headers.get("Content-Type", "").split(";")[0]
    if res.status_code != 200 or mime not in EXT:
        raise RuntimeError(f"HTTP {res.status_code}: {res.text[:500]}")
    path = stem + EXT[mime]
    with open(path, "wb") as f:
        f.write(res.content)
    return path


def remove_background(image_url, stem="result", max_wait=300):
    s = requests.Session()
    s.headers["x-api-key"] = KEY
    # One key per image: a retry with the same key returns the same job, never a second charge.
    idem = {"Idempotency-Key": str(uuid.uuid4())}

    for attempt in range(3):
        try:
            res = s.post(f"{API}/v1/remove", data={"image_url": image_url},
                         headers=idem, timeout=(10, 120))
            break
        except requests.ConnectionError:
            if attempt == 2:
                raise
            time.sleep(2)

    if res.status_code != 202:
        return save(res, stem)  # 200 is the image; anything else raises

    # 202: still processing. Wait for the same job.
    job_id = res.json()["id"]
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        time.sleep(2)  # the API sends Retry-After: 2
        res = s.get(f"{API}/v1/jobs/{job_id}/result", timeout=30)
        if res.status_code == 409 and res.json()["error"]["code"] == "not_ready":
            continue
        return save(res, stem)  # the image, or the job's own error
    raise TimeoutError(f"Job {job_id} is still running. Check /v1/jobs/{job_id} later.")


print(remove_background("https://example.com/photo.jpg"))

Ela precisa de Python 3 e requests (pip install requests). Dois detalhes passam fácil despercebidos. Primeiro, parar o script não para o job: ele ainda pode terminar e ser cobrado, e o resultado aparece no Studio da sua conta. Segundo, GET /v1/jobs/:id/result responde 409 not_ready enquanto o job está rodando, então trate isso como "aguarde", não como falha.

O mesmo fluxo em JavaScript (Node.js)

O mesmo fluxo em Node.js 18 ou mais recente, usando fetch, FormData e Blob nativos, com upload de um arquivo local:

import { readFile, writeFile } from "node:fs/promises"
import { randomUUID } from "node:crypto"

const API = "https://removebackground.dev"
const KEY = process.env.REMOVEBG_API_KEY // server side only
const EXT = { "image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp" }
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))

async function save(res, stem) {
  const mime = (res.headers.get("content-type") || "").split(";")[0]
  if (res.status !== 200 || !EXT[mime]) {
    throw new Error("HTTP " + res.status + ": " + (await res.text()).slice(0, 500))
  }
  const path = stem + EXT[mime]
  await writeFile(path, Buffer.from(await res.arrayBuffer()))
  return path
}

export async function removeBackground(filePath, stem = "result", maxWaitMs = 300000) {
  const form = new FormData()
  form.append("image_file", new Blob([await readFile(filePath)]), "upload")
  form.append("format", "png")

  const res = await fetch(API + "/v1/remove", {
    method: "POST",
    // Reuse the same Idempotency-Key if you retry this POST.
    headers: { "x-api-key": KEY, "Idempotency-Key": randomUUID() },
    body: form,
  })
  if (res.status !== 202) return save(res, stem)

  const { id } = await res.json()
  const deadline = Date.now() + maxWaitMs
  while (Date.now() < deadline) {
    await sleep(2000)
    const result = await fetch(API + "/v1/jobs/" + id + "/result", {
      headers: { "x-api-key": KEY },
    })
    if (result.status === 409) {
      const body = await result.json()
      if (body.error && body.error.code === "not_ready") continue
      throw new Error("Job " + id + ": " + body.error.code)
    }
    return save(result, stem)
  }
  throw new Error("Job " + id + " is still running. Check /v1/jobs/" + id + " later.")
}

console.log(await removeBackground("photo.jpg"))

A API aceita requisições CORS, o que ajuda em ferramentas e testes. Isso não torna seguro chamá-la de uma página web com sua chave dentro. Mais sobre isso na seção de segurança abaixo.

Passo 4: Controle a saída

A maioria dos apps não quer um recorte bruto em resolução total. Quer uma imagem de produto quadrada sobre branco, uma prévia pequena ou uma máscara. Pedir à API o arquivo final poupa uma segunda etapa de processamento. Estas são as opções de /v1/remove:

Toda opção custa o mesmo 1 crédito, e parâmetros desconhecidos são ignorados em silêncio, então um erro de digitação não vai gerar erro. Uma imagem quadrada para marketplace com o produto centralizado e 10% de margem fica assim:

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@product.jpg' \
  -F 'crop=1:1' -F 'padding=10%' \
  -F 'width=1000' -F 'height=1000' \
  -F 'format=jpg' -F 'bg_color=white' \
  -o product-square.jpg

Uma resposta bem-sucedida também traz headers úteis. X-Credits-Remaining mostra seu saldo depois da imagem. X-Matte-Confidence (0 a 1) diz o quão definida é a máscara, e X-Matte-Ambiguous-Ratio dá a proporção de pixels suaves, como cabelo, vidro ou desfoque de movimento. Registrar esses dois valores permite sinalizar recortes de baixa confiança para revisão humana em vez de conferir cada imagem.

Passo 5: Processe imagens em lote

Para importações de catálogo e reprocessamentos, não dispare centenas de requisições avulsas. POST /v1/batch coloca na fila até 100 URLs públicas de imagens como um único job, com as mesmas opções de /v1/remove, e responde 202 na hora:

import os
import time
import uuid
import requests

API = "https://removebackground.dev"
s = requests.Session()
s.headers["x-api-key"] = os.environ["REMOVEBG_API_KEY"]

urls = ["https://example.com/front.jpg", "https://example.com/back.jpg"]

job = s.post(f"{API}/v1/batch",
             json={"image_urls": urls, "format": "png", "size": "hd"},
             headers={"Idempotency-Key": str(uuid.uuid4())}, timeout=30)
job.raise_for_status()
job_id = job.json()["id"]  # save it: it's how you resume after a restart

while True:
    time.sleep(3)
    status = s.get(f"{API}/v1/jobs/{job_id}", timeout=30).json()
    if status["done"]:
        break

print(status["status"], "credits charged:", status["credits_charged"])
for item in status["items"]:
    if item["status"] != "succeeded":
        print("failed:", item["input"], item.get("error"))
        continue
    img = s.get(item["result_url"], timeout=60)
    with open(f"out-{item['position']}.{item['format']}", "wb") as f:
        f.write(img.content)

Algumas regras da documentação para levar em conta:

• O status do job termina como succeeded, partial (algumas imagens falharam) ou failed. Cada item em items tem seu próprio status e, em caso de falha, um código de erro.
• Entradas que não são URLs http(s) e URLs repetidas são descartadas e nunca cobradas. Quando alguma dessas contagens for maior que 0, associe os resultados por input em vez de pela posição.
• Você pode ter no máximo 3 jobs de lote abertos por conta. Um lote deixa de contar quando done é true.
• Se os créditos acabarem no meio do lote, as imagens concluídas continuam pagas e o restante é marcado como ignorado com out_of_credits, sem custo.
• A API não tem endpoint de cancelamento, webhooks nem download em ZIP, então o padrão é fazer polling. Ler um job é grátis e não tem limite de taxa.

Prefere um script pronto para rodar? O guia de lotes com Python mostra um fluxo completo de pasta para pasta.

Passo 6: Repita com segurança e mantenha a cobrança previsível

Timeouts de rede são a origem das cobranças em dobro. Seu cliente desiste, tenta de novo e agora existem dois jobs para uma imagem. A solução é um header Idempotency-Key: qualquer string única com até 255 caracteres, como um UUID, uma por imagem ou lote. Se você enviar a mesma requisição de novo com a mesma chave, recebe o job criado pela primeira, com o header Idempotent-Replayed: true, e sem nova cobrança. Reutilizar uma chave para outra imagem retorna 409 idempotency_key_reused.

A cobrança segue uma regra simples: 1 crédito quando a imagem dá certo, nada quando falha. Requisições rejeitadas antes do processamento, imagens ilegíveis e falhas depois dos retries do próprio provedor são gratuitas, e baixar de novo um resultado pronto é grátis enquanto ele estiver armazenado.

Limites para considerar no projeto

Se você precisa de mais de 60 imagens por minuto, a resposta é o endpoint de lote: uma requisição cobre até 100 imagens. Guarde os resultados no seu próprio bucket assim que baixá-los, porque depois de 48 horas os links de resultado respondem 410. Segundo a documentação do provedor, as imagens enviadas não são usadas para treinar modelos.

Migrando da API do remove.bg

O site independente e a API self-service do remove.bg terminam em 1º de dezembro de 2026, às 09:00 CET. A API vai para a Leonardo.Ai, o que exige mudar sua integração. Se você prefere não reescrever nada, o removebackground.dev tem um endpoint compatível com o remove.bg, e a migração é uma linha:

Você mantém o mesmo header X-Api-Key (com uma chave do removebackground.dev), os mesmos nomes de parâmetros, os mesmos headers de resposta e o mesmo formato de erros:

curl -H "X-Api-Key: $REMOVEBG_API_KEY" \
  -F 'image_file=@photo.jpg' -F 'size=auto' \
  -F 'crop=true' -F 'crop_margin=10%' -F 'bg_color=ffffff' \
  -o no-bg.jpg https://removebackground.dev/v1.0/removebg

Conheça as diferenças antes de trocar:

• Sem 202. O endpoint compatível espera até 110 segundos e depois retorna um timeout 503. O job continua rodando e é cobrado se der certo, então repetir essa requisição às cegas inicia um segundo job.
• Sem chaves de idempotência neste endpoint. Se você precisa de retries seguros, migre para /v1/remove com o tempo.
• Algumas opções são aceitas mas ignoradas: type e type_level (o objeto é detectado automaticamente), semitransparency e as opções de sombra (nenhuma sombra é adicionada).
• O tamanho sempre custa 1 crédito, inclusive a resolução total.

O guia de migração traz código de antes e depois para cURL, Python, Node e PHP, além de passos para Zapier, Make e n8n.

Mantenha sua chave de API fora do cliente

Esse é o erro que custa dinheiro de verdade. Se sua chave está em uma página web, um app mobile, um repositório público ou uma URL, qualquer pessoa pode lê-la e gastar seus créditos.

• Para permitir que seus usuários removam fundos, envie as imagens deles pelo seu backend e chame a API a partir dele.
• Adicione seu próprio login e limites de gasto por usuário nesse backend.
• Use uma chave por app ou ambiente.
• Se uma chave vazar, revogue-a na página da conta. Ela para de funcionar na hora. O provedor guarda apenas um hash de cada chave, então crie uma nova em vez de tentar recuperar a antiga.

Exemplo: recortes para thumbnails do YouTube

Se você cria ferramentas para criadores, thumbnails são um uso óbvio. Uma thumbnail é vista quase sempre em tamanho pequeno, então o recorte precisa segurá-la: um rosto ou produto, grande, com borda nítida sobre um fundo simples. O YouTube recomenda 3840 x 2160 px em 16:9 com largura mínima de 640 px, e aceita JPG ou PNG de até 50 MB pelo computador, mas só 2 MB pelo app mobile.

Do lado da API, é uma única chamada que devolve um PNG transparente recortado no objeto, pronto para colocar em uma tela 16:9:

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@me.jpg' \
  -F 'crop=true' -F 'padding=5%' \
  -o me-cutout.png

Tire uma foto de verdade para o recorte em vez de capturar um frame do vídeo, já que frames costumam ter desfoque de movimento, e deixe o canto inferior direito livre, porque o YouTube mostra a duração do vídeo ali. A página de thumbnails do YouTube cobre a parte de design, e nosso guia para conseguir seus primeiros 1.000 inscritos explica por que as thumbnails importam tanto.

Removendo fundos pelo ChatGPT, Claude ou Cursor

Nem todo trabalho precisa de código. O removebackground.dev também roda um servidor MCP em https://removebackground.dev/mcp, então você pode enviar uma foto no ChatGPT, Claude, Cursor, VS Code ou n8n e pedir para remover o fundo. No Claude Code, é um comando:

claude mcp add --transport http removebackground https://removebackground.dev/mcp

Depois digite /mcp no Claude Code para fazer login. O servidor oferece três ferramentas: remove_background, get_job para remoções que demoram mais que alguns segundos, e check_credits. Cada imagem custa 1 crédito, o mesmo que pela API.

Quanto custa

O removebackground.dev é pré-pago por uso, sem assinatura. Os créditos nunca expiram, imagens com falha são gratuitas e contas novas ganham 50 créditos grátis. Pela API, 1 crédito equivale a uma remoção de fundo bem-sucedida em resolução total.

Os preços são em USD, e créditos não usados podem ser reembolsados em até 30 dias. Preços por volume acima do Scale estão disponíveis sob consulta. Veja a página de preços para os detalhes atuais.

Conclusão

Uma boa integração para remover fundo se resume a alguns hábitos: mantenha a chave no seu servidor, verifique o status antes de salvar o corpo, espere o job em vez de reenviar depois de um 202, envie um Idempotency-Key em cada POST e use o endpoint de lote para trabalho em massa.

A referência completa, incluindo a especificação OpenAPI 3.1, está na documentação da API. Se você trabalha com vídeo além de imagens, nossa comparação de APIs de transcrição do YouTube e nosso guia de integração de voz para texto usam os mesmos padrões de produção para texto.