Referência da API de remoção de fundo

Consulte parâmetros, formatos de resposta e diferenças em relação à API do remove.bg. Veja exemplos com arquivo, URL e Base64 e os limites de cada entrada.

POST https://removebgtool.net/v1.0/removebg

curl --fail-with-body --max-time 180 \
  -H 'X-API-Key: YOUR_API_KEY' \
  -F 'image_file=@image.jpg' \
  -F 'size=auto' \
  'https://removebgtool.net/v1.0/removebg' -o no-bg.png

Requisição

Envie X-API-Key. Use multipart/form-data para image_file; JSON ou dados URL-encoded aceitam image_url ou image_file_b64. Informe exatamente uma fonte. Padrões: crop=false e format=auto, com PNG para transparência e JPG para saída opaca. bg_color aceita nomes CSS ou hex de 3/4/6/8 dígitos. JPG compõe a transparência sobre branco.

curl --fail-with-body --max-time 180 \
  -H 'X-API-Key: YOUR_API_KEY' \
  -F 'image_url=https://example.com/photo.jpg' \
  -F 'format=png' \
  'https://removebgtool.net/v1.0/removebg' -o result.png

# JSON input and JSON output
curl --fail-with-body --max-time 180 \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data '{"image_file_b64":"YOUR_PADDED_BASE64","format":"png"}' \
  'https://removebgtool.net/v1.0/removebg'

import requests

with open('image.jpg', 'rb') as image:
    response = requests.post(
        'https://removebgtool.net/v1.0/removebg',
        headers={'X-API-Key': 'YOUR_API_KEY'},
        files={'image_file': image},
        data={'size': 'auto'},
        timeout=180,
    )
response.raise_for_status()
with open('no-bg.png', 'wb') as output:
    output.write(response.content)

import { readFile, writeFile } from 'node:fs/promises';

const form = new FormData();
form.append('image_file', new Blob([await readFile('image.jpg')]), 'image.jpg');
form.append('size', 'auto');
const response = await fetch('https://removebgtool.net/v1.0/removebg', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY' },
  body: form,
  signal: AbortSignal.timeout(180000),
});
if (!response.ok) throw new Error(await response.text());
await writeFile('no-bg.png', Buffer.from(await response.arrayBuffer()));

Resposta

HTTP 200 retorna os bytes da imagem. Com Accept: application/json, receba data.result_b64 e dimensões. Cabeçalhos: X-Width, X-Height, X-Credits-Charged, X-Foreground-Top/Left/Width/Height e X-Request-ID. Coordenadas do primeiro plano se referem à tela de entrada normalizada. Sem classificação ou X-Type. GET /v1.0/account retorna data.attributes.credits e api.free_calls (0).

{
  "data": {
    "result_b64": "...",
    "result_width": 625,
    "result_height": 400,
    "credits_charged": 1
  }
}

Limites e diferenças

Entrada: ≤22 MB, ≤50 MP, cada dimensão de 33 a 9999 pixels, JPG/PNG/WebP de quadro único. URLs HTTPS devem ser públicas, diretas e usar a porta 443; redirecionamentos e redes privadas são rejeitados. size padrão: preview (0,25 MP); medium=1,5 MP, hd=4 MP, full/4k/auto=25 MP, 50MP=50 MP. PNG e auto têm limite de 10 MP. Não há ampliação. Ao contrário do remove.bg, auto não escolhe o tamanho pelo saldo.

A API usa os créditos existentes da conta. O valor por imagem aparece no painel e em X-Credits-Charged. Prévia e resolução completa têm o mesmo custo. Não há uma franquia mensal gratuita adicional de API.

Erros e novas tentativas

400 entrada/parâmetros inválidos · 402 créditos insuficientes · 403 chave/plano inválido · 409 conflito/em andamento/expiração de idempotência · 415 codificação não suportada · 429 limite de requisições · 502/503 falha ou sobrecarga do provedor · 504 tempo esgotado. Respeite Retry-After em 429/503 e use espera exponencial em erros 5xx temporários. Mantenha as chaves no servidor.

{
  "errors": [
    {
      "title": "Insufficient credits.",
      "code": "insufficient_credits"
    }
  ]
}

Idempotency-Key é opcional: reutilize a mesma chave, imagem e parâmetros para repetir um resultado bem-sucedido por 10 minutos sem nova cobrança. A repetição mantém X-Credits-Charged e adiciona X-Idempotent-Replayed: true. Requisições em andamento retornam 409. Chaves com falha ou expiradas ficam reservadas: use outra para uma nova requisição cobrada. Sem o cabeçalho, cada requisição é independente. Use timeout de 180 segundos.

Checklist de migração

1. Crie uma chave em um plano com API. 2. Troque o domínio e mantenha /v1.0/removebg. 3. Confira limites e parâmetros não suportados. 4. Teste imagens, erros e cobrança. 5. Migre a produção. Este serviço é independente do remove.bg.Ver guia de migração →

Uma interface compatível não significa resultados de IA idênticos. Teste suas imagens antes de migrar.