API do bgCut.net

Remova fundos a partir dos seus próprios apps, lojas ou pipelines com uma única requisição HTTPS.

URL base: https://bgcut.net/api/v1 · Obtenha sua chave em Chaves de API.

Autenticação

Toda requisição deve incluir sua chave de API no cabeçalho X-Api-Key. As chaves são criadas e revogadas na sua conta. Cada chave pode receber um nome, para que você possa alterná-las por aplicação.

X-Api-Key: bgc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Como alternativa, envie-a como token Bearer: Authorization: Bearer bgc_…

POST /remove

Envie a imagem como arquivo multipart, como URL ou codificada em base64. Por padrão, a resposta é a imagem resultante (binária).

Parâmetros

ParâmetroTipoDescrição
image_filefileO arquivo de imagem (multipart/form-data). JPG, PNG, WebP, GIF, BMP, TIFF; máx. 25 MB / 30 MP.
image_urlstringURL pública da imagem a ser baixada em vez de enviada.
image_file_b64stringImagem codificada em base64 (opcionalmente com prefixo data:).
sizeauto | preview | fullpreview = até 640 px (usa sua cota mensal gratuita, sem créditos); full = resolução original (1 crédito); auto (padrão) = full quando você tem créditos, caso contrário preview.
formatpng | jpg | webpFormato de saída. png mantém a transparência; jpg é mesclado sobre bg_color (branco por padrão).
modelfast | hq | portraitlite (padrão, ~6 s, melhor equilíbrio), fast (~0,5 s, qualidade de prévia), hq (~15 s, qualidade máxima), portrait (~0,3 s, apenas pessoas).
bg_colorstringCor hexadecimal do fundo, p. ex. #ffffff. Omita para fundo transparente.
bg_blurnumberMantém o fundo original, mas o desfoca com este raio em pixels (1–200), p. ex. 25 para um efeito de modo retrato. Substitui bg_color.
cropbooleanRecorta a saída para a área delimitadora do objeto.
crop_marginintegerMargem extra em pixels ao redor do objeto ao recortar (0–200).
roistringRegião de interesse como frações x,y,w,h (0–1). A IA analisa apenas o interior deste retângulo; tudo o que estiver fora fica transparente.
feathernumberSuaviza as bordas com este raio em pixels (0–5).
qualityintegerQualidade JPG/WebP de 50 a 100 (padrão 92).
responsebinary | jsonbinary (padrão) retorna a imagem; json retorna os metadados e a imagem em base64.

Respostas

Requisições bem-sucedidas retornam HTTP 200 com os bytes da imagem e estes cabeçalhos:

HTTP/1.1 200 OK
Content-Type: image/png
X-Credits-Charged: 1
X-Credits-Remaining: 149
X-Free-Remaining: 5
X-Width: 3000
X-Height: 2000
X-Image-Id: 1f3a…
X-Type: hd

Com response=json, você recebe:

{
  "ok": true,
  "image": { "id": "1f3a…", "width": 3000, "height": 2000, "format": "png", "type": "hd", "bytes": 812345, "bbox": [120, 40, 2810, 1990], "data": "iVBORw0KGgo…" },
  "credits_charged": 1,
  "credits_remaining": 149,
  "free_remaining": 5
}

GET /account

curl https://bgcut.net/api/v1/account -H "X-Api-Key: bgc_…"

{ "ok": true, "email": "[email protected]", "credits": 149, "free_remaining": 5, "free_per_month": 5, "free_max_width": 640, "rate_limit_per_minute": 60 }

GET /images

Retorna as últimas 100 imagens processadas com suas chaves de API, incluindo uma URL do editor para refiná-las no navegador.

Erros

Os erros são retornados em JSON com um código de erro e uma mensagem legível:

{ "ok": false, "error": "insufficient_credits", "message": "No credits left. Buy credits at https://bgcut.net/pricing or request size=preview." }
HTTPerrorDescrição
400bad_request / missing_imageParâmetros ausentes ou inválidos.
401auth_required / invalid_keyChave de API ausente, inválida ou revogada.
402insufficient_credits / free_quota_exceededSem créditos (para tamanho completo) ou cota gratuita esgotada (para prévia).
422too_large / bad_type / fetch_failedNão foi possível ler ou baixar a imagem.
429rate_limitedRequisições em excesso – reduza a frequência ou entre em contato conosco para obter limites maiores.
500processing_failedFalha no processamento do nosso lado – nada será cobrado.

Código de exemplo

Todos os exemplos usam o mesmo endpoint. Baixe a coleção completa de exemplos: bgcut-api-examples.zip

SDK PHP oficial
Biblioteca cliente de código aberto com resultados tipados, classes de erro e exemplos prontos para uso. Licença MIT.
composer require bgcut-net/bgcut-php
GitHub

Limites

  • 60 requisições por minuto por chave de API (limites maiores mediante solicitação).
  • Máx. 25 MB e 30 megapixels por imagem; imagens maiores são reduzidas.
  • As imagens processadas ficam armazenadas por 30 dias e podem ser refinadas no editor web.
  • Requisições com falha nunca são cobradas; a cobrança é estornada automaticamente se a geração do resultado falhar.

Comece a integrar

Crie uma conta gratuita, gere uma chave e faça sua primeira chamada em menos de um minuto.

Obter chave de API Preços