API de remoção de fundo: uma requisição de ida, o PNG pronto de volta.

Envie sua imagem

POST /v1/remove aceita a imagem de quatro formas. Envie uma delas; se uma requisição trouxer várias, image_file tem prioridade, depois image_file_b64, depois image_url e por último o corpo bruto. Estes exemplos leem sua chave da variável de ambiente REMOVEBG_API_KEY (defina com export REMOVEBG_API_KEY=…); repare nas aspas duplas, que deixam o shell preencher o valor.

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

Todos os exemplos salvam o corpo em um arquivo. Esse arquivo só é uma imagem quando o status é 200; veja Trate a resposta.

Trate a resposta

A maioria das imagens avulsas volta pronta na mesma resposta. Quando a fila está muito movimentada e uma imagem demora mais de uns 55 segundos, você recebe 202 Accepted com um id de job. O job continua rodando: busque o resultado com o id. Enviar a imagem de novo iniciaria um segundo job e poderia custar um segundo crédito.

Um exemplo completo

Trata a imagem pronta, um 202, um job que falha e um limite de tempo local. Envia a imagem uma única vez e só repete as consultas de status, que são 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: resending with the same key returns the same job, never a second
    # charge, so this POST is safe to retry after a timeout or a dropped connection.
    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 = the image; anything else raises

    # 202: still processing. Wait for the same job; never send the image again.
    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 it later at /v1/jobs/{job_id}.")


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

• Parar seu script não para o job; ele ainda pode terminar e ser cobrado. O resultado aparece no seu Studio.
• Os limites de tempo são escolha sua, não uma promessa nossa; a maioria das imagens fica pronta em poucos segundos.
• O endpoint compatível com o remove.bg se comporta de outro jeito: ele nunca responde 202 (veja abaixo).

Lotes, do início ao fim

1. Enviar

curl -X POST https://removebackground.dev/v1/batch \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "image_urls": ["https://example.com/front.jpg", "https://example.com/back.jpg"], "format": "png", "size": "hd" }'

Até 100 URLs públicas de imagens, mais qualquer uma das opções de /v1/remove. As duas URLs de exemplo acima custariam até 2 créditos se fossem imagens reais. A resposta vem na hora:

202 Accepted
{
  "id": "3f6c2a9e-8d1b-4c7a-9e2f-5b8d0a1c4e77",
  "status": "queued",
  "total": 2,
  "invalid": 0,
  "duplicates": 0,
  "status_url": "https://removebackground.dev/v1/jobs/3f6c2a9e-8d1b-4c7a-9e2f-5b8d0a1c4e77"
}

invalid conta as entradas que não são URLs http(s) e duplicates conta as repetidas; ambas são descartadas e nunca cobradas. Guarde o id: é com ele que você retoma o job depois de uma reinicialização.

2. Consulte o job

GET /v1/jobs/:id a cada poucos segundos até done ser true. status passa de queued para processing e termina como succeeded, partial (algumas imagens falharam) ou failed. Um item que está sendo tentado de novo mostra retrying.

{
  "id": "3f6c2a9e-…",
  "status": "partial",
  "done": true,
  "total": 2, "succeeded": 1, "failed": 1, "skipped": 0,
  "credits_charged": 1,
  "items": [
    { "position": 0, "input": "https://example.com/front.jpg", "status": "succeeded",
      "removal_id": "…", "width": 1600, "height": 1200, "format": "png",
      "result_url": "https://removebackground.dev/v1/jobs/3f6c2a9e-…/result?item=0" },
    { "position": 1, "input": "https://example.com/back.jpg", "status": "failed",
      "error": { "code": "fetch_failed", "message": "…" } }
  ]
}

3. Baixe cada resultado

GET /v1/jobs/:id/result?item=N para cada item bem-sucedido (ou use a result_url dele). item é a position, começando em zero. As posições seguem a sua lista depois que as URLs inválidas e repetidas são removidas, então, quando algum desses contadores for maior que 0, associe os resultados pelo input, e não pelo índice.

• Um lote deixa de contar para o limite de 3 lotes abertos assim que done é true.
• A API não tem endpoint de cancelamento, webhooks nem download em ZIP. Lotes iniciados na página do Bulk podem ser cancelados ou baixados em ZIP por lá.

Novas tentativas, duplicatas e cobrança

Envie uma Idempotency-Key e as novas tentativas não cobram duas vezes. Adicione um header Idempotency-Key (qualquer string única de até 255 caracteres, como um UUID) em POST /v1/remove ou POST /v1/batch, uma chave por imagem ou lote. Se você enviar a mesma requisição de novo com a mesma chave, recebe o job criado pela primeira, com Idempotent-Replayed: true: nenhum job novo e nenhuma cobrança nova, mesmo que a primeira requisição ainda esteja rodando. A mesma chave com outra imagem ou outras opções responde 409 idempotency_key_reused. As chaves pertencem à sua conta e não expiram.

Sem chave, cada POST cria um job novo, e cada job bem-sucedido custa 1 crédito (o endpoint compatível com o remove.bg POST /v1.0/removebg não aceita chaves). Consultar um job (GET /v1/jobs/…) é sempre grátis e pode ser repetido sem risco.

IDEMPOTENCY_KEY=$(uuidgen)   # one per image; send the same one on every retry

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

O que custa um crédito

Quando tentar de novo

Limites e armazenamento

Por quanto tempo os resultados ficam guardados

Cada resultado fica guardado de forma privada na sua conta por 48 horas depois de criado e depois é apagado. Até lá, você pode baixá-lo de novo, de graça, com GET /v1/jobs/:id/result ou pelo seu Studio. Depois disso, os links de resultado respondem 410 result_unavailable; processar a imagem de novo é um job novo. Os registros de status do job continuam disponíveis depois que a imagem é apagada. Veja a política de privacidade para saber como os envios são tratados; não usamos suas imagens para treinar modelos.

Segurança

Mantenha sua chave de API em um servidor que você controla. Não coloque a chave em código de navegador, apps de celular, repositórios públicos ou URLs. Para deixar seus próprios usuários removerem fundos, envie as imagens deles pelo seu backend e adicione lá o seu próprio login e limites de gasto.

• A API permite CORS para funcionar a partir de ferramentas e código no servidor. Isso não torna seguro colocar uma chave em uma página web: qualquer pessoa pode lê-la ali.
• Todas as chaves de uma conta usam o mesmo saldo de créditos. Crie uma chave separada por app ou ambiente na página da sua conta, para poder revogar uma sem quebrar as outras.
• Se uma chave vazar, revogue-a imediatamente na página da conta (ela para de funcionar na hora) e crie uma nova. Guardamos só um hash de cada chave, então não conseguimos mostrá-la de novo.

Solução de problemas