API REST + IA

Uma API para remover fundo, consultar saldo e automatizar imagens em escala.

Integre por upload ou URL remota, acompanhe o consumo da sua API key, habilite HD com créditos e conecte as ferramentas de IA no mesmo backend.

Começar em 5 minutos OpenAPI interativo

Autenticação

X-API-Key

Chaves criadas no dashboard, prontas para backend, scripts e automações.

Entradas

Upload e URL

Envie arquivo multipart ou use uma imagem publica via HTTP/HTTPS.

Observabilidade

Headers e créditos

Receba tamanho da imagem, modo de processamento e saldo de créditos restante.

Demo visual

Veja a API como produto, não só como endpoint.

Esta demo resume as funcionalidades principais: antes e depois do recorte, processamento por URL, leitura de saldo e os recursos de IA.

Demo local, sem consumir seu saldo

Comparador antes e depois

Foto real de produto processada pela mesma API publica mostrada nesta documentacao.

PNG transparente real

Foto original de produto antes do recorte

⇄

Antes Depois

Entrada

Upload multipart ou URL remota publica.

Saida

PNG transparente com metadados uteis nos headers.

Créditos

HD, IA e URL remota usam saldo pré-pago.

Processamento classico por upload

Ideal para formulários, admin panels e uploads diretos do seu produto.

POST /api/remove-bg
X-API-Key: rbg_sua_chave

file=@produto.jpg
hd=true

Resposta util

X-Api-Quota-Remaining: 742
X-Processing-Mode: hd
X-Output-Width: 1600
X-Watermark-Applied: false

Processamento por URL remota

Perfeito para pipelines server-to-server quando a imagem já está no seu CDN.

POST /api/remove-bg-url
Content-Type: application/json
X-API-Key: rbg_sua_chave

{
  "image_url": "https://cdn.seusite.com/produto.webp",
  "hd": true
}

O que a rota protege

bloqueio de localhost e IPs privados
validacao de formato e tamanho
limite de redirecionamentos

Leitura de saldo e status da conta

Use como preflight antes de filas, lotes e tarefas agendadas.

GET /api/account
X-API-Key: rbg_sua_chave

{
  "billing_model": "credits",
  "user": { "credit_balance": 742 },
  "usage": { "credit_balance": 742 }
}

Ferramentas de IA

Depois do recorte, gere fundo por prompt e melhore imagens sem sair do mesmo ecossistema.

POST /api/ai/background
{
  "prompt": "fundo de estudio clean com sombra suave",
  "size": "1024x1024"
}

POST /api/ai/upscale
{
  "image_url": "https://cdn.seusite.com/resultado.png",
  "scale": 4
}

Quickstart

Se você quer sair do zero e fazer a primeira chamada o mais rápido possível, siga estes 4 passos.

Abrir dashboard

Passo 1

Crie sua chave

No dashboard, gere uma API key. O token bruto aparece apenas uma vez.

Passo 2

Descubra capacidades

Consulte GET /api/capabilities para ler limites, custos e recursos.

Passo 3

Envie a imagem

Use upload multipart ou URL remota para receber PNG transparente.

Passo 4

Monitore o saldo

Leia os headers de resposta ou chame GET /api/account.

curl -X POST https://api.removebg.com.br/api/remove-bg \
  -H "X-API-Key: rbg_sua_chave" \
  -F "file=@produto.jpg" \
  -F "hd=true" \
  -o produto-sem-fundo.png

Catálogo de endpoints

A API combina descoberta, operação, saldo e recursos de IA em uma única superfície consistente.

Público

`GET /api/health`

Health check simples com status, modelo carregado e versão da API.

Público

`GET /api/capabilities`

Descobre limites, formatos aceitos, custos, docs OpenAPI e recursos habilitados.

API key

`POST /api/remove-bg`

Remove o fundo a partir de upload multipart e responde com PNG.

API key

`POST /api/remove-bg-url`

Busca uma imagem pública por URL e devolve o PNG processado.

API key

`GET /api/account`

Consulta saldo, consumo recente e metadados da API key.

Créditos

`POST /api/remove-bg/batch`

Processa várias imagens e responde com ZIP. Ideal para lotes internos.

`POST /api/ai/background`

Gera novos fundos com prompt de texto para compor a imagem final.

`POST /api/ai/upscale`

Aumenta a resolução da imagem via IA em 2x ou 4x.

Autenticação e créditos

API key

Todas as rotas de integração usam o header X-API-Key. O formato do token sempre começa com rbg_.

X-API-Key: rbg_sua_chave_aqui

JWT do dashboard

Rotas de conta e painel usam Authorization: Bearer com sessão do Supabase. Isso vale para CRUD de API keys e informações internas do usuário no dashboard.

As rotas REST de integração para apps externos devem preferir API key.

Uso	Custo	Acesso API	Modo HD	Notas
Free	R$ 0	Amostras grátis	Não	Bom para testar no site. Processamento via API exige saldo.
Créditos	A partir de R$ 9,90	Consome saldo	Sim	HD, sem marca d'água, IA e melhor fluxo operacional.

Exemplos reais de uso

Além do hello world, estes cenários mostram como a API entra em fluxos de produto reais.

Gerar chave

E-commerce

Catálogo de produtos

Receba a foto enviada pelo lojista, remova o fundo e publique o PNG final no seu CDN.

POST /api/remove-bg
file=@tenis-frontal.jpg
hd=true

Resultado esperado: imagem limpa para marketplaces, ads e vitrines.

SaaS e automacao

Pipelines por URL

Quando o arquivo ja esta no storage, processe por URL sem reupload e encadeie com sua fila.

POST /api/remove-bg-url
{
  "image_url": "https://cdn.seusite.com/item.webp",
  "hd": true
}

Resultado esperado: integracao server-to-server com menos latencia operacional.

Conta e billing

Painel de saldo

Use o endpoint de conta para bloquear jobs grandes, alertar saldo baixo e abrir tickets proativos.

GET /api/account
X-API-Key: rbg_sua_chave

Resultado esperado: monitoramento real de saldo, consumo e uso por chave.

Remover fundo por upload

O endpoint principal recebe multipart/form-data e devolve um PNG com canal alfa. Ele pode operar em modo padrão ou HD. O uso pago consome créditos da carteira do usuário.

POST https://api.removebg.com.br/api/remove-bg

Campo	Tipo	Descrição
file	Arquivo	JPG, PNG ou WebP, com até 10 MB.
hd	Boolean	Quando `true`, tenta manter a resolução original para requests pagos.

curl -X POST https://api.removebg.com.br/api/remove-bg \
  -H "X-API-Key: rbg_sua_chave" \
  -F "file=@foto.jpg" \
  -F "hd=true" \
  -o saida.png

import requests

with open("foto.jpg", "rb") as source:
    response = requests.post(
        "https://api.removebg.com.br/api/remove-bg",
        headers={"X-API-Key": "rbg_sua_chave"},
        files={"file": source},
        data={"hd": "true"},
        timeout=60,
    )

response.raise_for_status()
with open("saida.png", "wb") as target:
    target.write(response.content)

print(response.headers.get("X-Api-Quota-Remaining"))

Headers de resposta

X-Api-Quota-Remaining	Compatibilidade legado. No modelo atual, consulte saldo em `/api/billing/account`.
X-Processing-Mode	`standard` ou `hd`.
X-Source-Origin	`upload` quando o arquivo veio por multipart.
X-Source-Width / Height	Dimensões da imagem de entrada.
X-Output-Width / Height	Dimensões do PNG final.
X-Watermark-Applied	Indica se o resultado recebeu marca d'água.

Remover fundo por URL remota

Esse endpoint foi criado para automacoes server-to-server. Ele baixa a imagem remota, valida o host, bloqueia localhost e enderecos privados e responde com o PNG processado.

POST https://api.removebg.com.br/api/remove-bg-url

Body JSON

{
  "image_url": "https://exemplo.com/assets/produto.webp",
  "hd": true
}

Regras da URL remota

Apenas URLs publicas HTTP ou HTTPS.
Hosts locais, privados ou reservados sao rejeitados.
Redirecionamentos sao limitados.
O arquivo continua sujeito ao limite de 10 MB e formatos permitidos.

curl -X POST https://api.removebg.com.br/api/remove-bg-url \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rbg_sua_chave" \
  -d '{"image_url":"https://exemplo.com/foto.png","hd":true}' \
  --output foto-sem-fundo.png

const response = await fetch("https://api.removebg.com.br/api/remove-bg-url", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "rbg_sua_chave"
  },
  body: JSON.stringify({
    image_url: "https://exemplo.com/produto.jpg",
    hd: true
  })
});

const buffer = Buffer.from(await response.arrayBuffer());

Consultar conta, saldo e consumo

O endpoint GET /api/account ajuda a montar dashboards internos, alarmes de consumo e validações antes de iniciar jobs maiores.

curl https://api.removebg.com.br/api/account \
  -H "X-API-Key: rbg_sua_chave"

{
  "ok": true,
  "billing_model": "credits",
  "user": {
    "id": "user-123",
    "credit_balance": 742
  },
  "api_key": {
    "id": "key-123",
    "name": "producao",
    "key_prefix": "rbg_abcd"
  },
  "usage": {
    "credit_balance": 742,
    "credits_used": 240
  }
}

Quando usar

Checar saldo antes de rodar lotes ou filas internas.

Exibir saldo restante no painel do seu próprio SaaS.

Auditar qual chave está em uso e quando ela foi usada por último.

Recursos de IA

Além do recorte, a plataforma expõe endpoints para gerar fundo por prompt, melhorar imagem e expandir canvas com IA generativa. Eles ajudam a empacotar um workflow mais completo para devs, studios e e-commerce.

`POST /api/ai/background`

Recebe um prompt e o tamanho final desejado. Responde com URL da imagem gerada.

{
  "prompt": "fundo de estúdio clean com sombra suave",
  "size": "1024x1024"
}

`POST /api/ai/upscale`

Recebe a URL da imagem e o fator 2x ou 4x. Responde com URL do resultado melhorado.

{
  "image_url": "https://cdn.seusite.com/resultado.png",
  "scale": 4
}

`POST /api/ai-image/expand`

Recebe upload multipart, novo aspect ratio, posicionamento e qualidade para gerar outpainting real com IA.

image=@foto.jpg
aspectRatio=9:16
position=center
quality=high
outputFormat=image/png

`POST /api/watermark-removal/remove`

Remove marca d'água com inpainting. Envie a imagem e uma máscara PNG do mesmo tamanho, com branco na área a reconstruir e preto no restante.

curl -X POST https://api.removebg.com.br/api/watermark-removal/remove \
  -H "X-API-Key: rbg_sua_chave" \
  -F "image=@foto.jpg" \
  -F "mask=@mascara.png" \
  -F "quality=standard" \
  -F "outputFormat=image/png" \
  --output sem-marca.png

import requests

files = {
  "image": open("foto.jpg", "rb"),
  "mask": open("mascara.png", "rb"),
}
data = {"quality": "standard", "outputFormat": "image/png"}
headers = {"X-API-Key": "rbg_sua_chave"}

r = requests.post(
  "https://api.removebg.com.br/api/watermark-removal/remove",
  headers=headers,
  files=files,
  data=data,
)
r.raise_for_status()
open("sem-marca.png", "wb").write(r.content)

const form = new FormData();
form.append("image", imageFile);
form.append("mask", maskPngFile);
form.append("quality", "high");
form.append("outputFormat", "image/png");

const res = await fetch("/api/watermark-removal/remove", {
  method: "POST",
  headers: { "X-API-Key": "rbg_sua_chave" },
  body: form
});

const blob = await res.blob();

Erros, limites e comportamento esperado

Status	Code	Quando acontece
400	EMPTY / INVALID_IMAGE	Arquivo vazio, corrompido ou não legível.
400	REMOTE_FETCH_ERROR	Falha ao buscar a imagem remota ou URL não permitida.
401	BAD_API_KEY	Chave ausente, inválida ou revogada.
413	TOO_LARGE	Imagem acima do limite permitido.
415	BAD_TYPE	Formato não suportado.
402	INSUFFICIENT_CREDITS	Saldo de créditos insuficiente para a operação.
500	PROCESSING_ERROR	Falha inesperada durante o processamento. Tente novamente.

Boas práticas de integração

Leia os headers

Eles ajudam a registrar saldo restante, modo HD e dimensões processadas sem chamadas extras.

Use account para preflight

Antes de jobs maiores, consulte /api/account e evite filas quebrando por falta de saldo.

Prefira URL remota em backend

Quando a imagem já estiver em um CDN público, evite reupload e processe direto por URL.

Mantenha retry consciente

Em erro 500 ou 502, aplique retry com backoff. Em 4xx, corrija o request antes de repetir.

Precisa de volume maior na API?

Podemos estruturar camadas dedicadas para operação contínua, SLA e volume customizado para marketplace, apps de edição e pipelines de e-commerce.

Ver preços Falar com o time