API di bgCut.net

Rimozione degli sfondi da app, negozi online o pipeline con una singola richiesta HTTPS.

URL di base: https://bgcut.net/api/v1 · La chiave si ottiene in Chiavi API.

Autenticazione

Ogni richiesta deve includere la chiave API nell'header X-Api-Key. Le chiavi si creano e si revocano nel proprio account; a ogni chiave si può assegnare un nome per poterle ruotare per singola applicazione.

X-Api-Key: bgc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

In alternativa, inviarla come token Bearer: Authorization: Bearer bgc_…

POST /remove

Inviare l'immagine come file multipart, come URL o codificata in base64. Per impostazione predefinita la risposta è l'immagine risultante (binaria).

Parametri

ParametroTipoDescrizione
image_filefileIl file immagine (multipart/form-data). JPG, PNG, WebP, GIF, BMP, TIFF; max 25 MB / 30 MP.
image_urlstringURL pubblico dell'immagine da scaricare anziché caricarla.
image_file_b64stringImmagine codificata in base64 (facoltativamente con prefisso data:).
sizeauto | preview | fullpreview = fino a 640 px (usa la quota mensile gratuita, nessun credito); full = risoluzione originale (1 credito); auto (predefinito) = full se sono disponibili crediti, altrimenti preview.
formatpng | jpg | webpFormato di output. png mantiene la trasparenza; jpg viene appiattito su bg_color (bianco per impostazione predefinita).
modelfast | hq | portraitfast (predefinito, ~1 s), hq (qualità superiore, più lento), portrait (ottimizzato per le persone).
bg_colorstringColore esadecimale dello sfondo, es. #ffffff. Omettere per uno sfondo trasparente.
bg_blurnumberMantiene lo sfondo originale ma lo sfoca con questo raggio in pixel (1–200), ad es. 25 per un effetto modalità ritratto. Ha la precedenza su bg_color.
cropbooleanRitaglia l'output al riquadro di delimitazione del soggetto.
crop_marginintegerMargine aggiuntivo in pixel attorno al soggetto durante il ritaglio (0–200).
roistringArea di interesse come frazioni x,y,w,h (0–1). L'IA analizza solo l'interno di questo rettangolo; tutto ciò che è all'esterno diventa trasparente.
feathernumberAmmorbidisce i bordi con questo raggio in pixel (0–5).
qualityintegerQualità JPG/WebP 50–100 (predefinita 92).
responsebinary | jsonbinary (predefinito) restituisce l'immagine; json restituisce i metadati più l'immagine in base64.

Risposte

Le richieste riuscite restituiscono HTTP 200 con i byte dell'immagine e questi header:

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

Con response=json si ottiene:

{
  "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

Restituisce le ultime 100 immagini elaborate con le proprie chiavi API, incluso un URL dell'editor per rifinirle nel browser.

Errori

Gli errori sono in formato JSON con un codice di errore e un messaggio leggibile:

{ "ok": false, "error": "insufficient_credits", "message": "No credits left. Buy credits at https://bgcut.net/pricing or request size=preview." }
HTTPerrorDescrizione
400bad_request / missing_imageParametri mancanti o non validi.
401auth_required / invalid_keyChiave API mancante, non valida o revocata.
402insufficient_credits / free_quota_exceededCrediti esauriti (per la dimensione intera) o quota gratuita esaurita (per l'anteprima).
422too_large / bad_type / fetch_failedImpossibile leggere o scaricare l'immagine.
429rate_limitedTroppe richieste: ridurre la frequenza o contattarci per limiti più elevati.
500processing_failedElaborazione non riuscita per un problema nostro: non viene addebitato nulla.

Codice di esempio

Tutti gli esempi usano lo stesso endpoint. Scaricare la raccolta completa di esempi: bgcut-api-examples.zip

Limiti

  • 60 richieste al minuto per chiave API (limiti più elevati su richiesta).
  • Max 25 MB e 30 megapixel per immagine; le immagini più grandi vengono ridimensionate.
  • Le immagini elaborate vengono conservate per 30 giorni e possono essere rifinite nell'editor web.
  • Le richieste non riuscite non vengono mai addebitate; l'addebito viene rimborsato automaticamente se la generazione del risultato non riesce.

Iniziare l'integrazione

Creare un account gratuito, generare una chiave ed effettuare la prima chiamata in meno di un minuto.

Ottenere una chiave API Prezzi