RemBG Background Removal API – Documente pentru dezvoltatori și Ghid de integrare






OpenAPI · Loc de joacă live

Explorați API-ul complet — rulați solicitări reale în browserul dvs.

Răsfoiți fiecare punct final, parametri și răspunsuri. Încercați solicitările cu cheia API, apoi obțineți oricând specificația brută de la /api/openapi.

Lansați referința interactivă

Instalarea rembg.js

latest npm versionGitHub starsnpm downloadslicenseGitHub issues

npm i @remove-background-ai/rembg.js
                        

API Reference for rembg.js

@remove-background-ai/rembg.js is a zero-config Node.js wrapper for the free Rembg API, enabling background removal with simple, customizable parameters.

Parameters for RemBG.js
ParameterTypeRequiredDefaultDescription
apiKeystring
Required

Your Rembg API key
inputImagestring | Buffer | { base64: string }
Required

Image file, buffer, or base64 payload
onDownloadProgress(event) => void
Optional

Hook for upload progress events
onUploadProgress(event) => void
Optional

Hook for download progress events
options.formatwebp (default) | png
Optional
webp
Specifies the output image format. Either "webp" (default) or "png"
options.returnBase64boolean
Optional
false
Return Base64 string instead of file
options.returnMaskboolean
Optional
false
Return only the alpha mask
options.wnumber
Optional

Target width (maintains aspect ratio)
options.hnumber
Optional

Target height (maintains aspect ratio)
options.exact_resizeboolean
Optional
false
Force exact width × height (may distort)
options.anglenumber
Optional
0
Rotation angle in degrees
options.expandboolean
Optional
true
Add padding so rotated images aren’t cropped
options.bg_colorstring
Optional
-
Optional solid background color in hex (e.g. #FFFFFFFF) or named color (e.g. "red", "blue")
  • Configurarea mediului: Asigurați-vă că aveți un fișier .env în rădăcina proiectului dvs. care conține cheia dvs. API.

  • Importarea modulelor necesare: Începeți prin a importa funcția rembg din @remove-background-ai/rembg.js și modulul dotenv pentru a gestiona variabilele de mediu.

  • Configurarea apelurilor de progres: Biblioteca oferă apeluri onDownloadProgress și onUploadProgress pentru a urmări progresul operațiunilor cu fișiere. În exemplul oferit, înregistrăm aceste evenimente direct în consolă.

Acum, să aruncăm o privire mai atentă la un exemplu de utilizare:


// script.mjs file

import  { rembg } from '@remove-background-ai/rembg.js';
import dotenv from 'dotenv';
// Load environment variables from .env file
dotenv.config();

// API_KEY will be loaded from the .env file
const API_KEY = process.env.API_KEY;

// log upload and download progress
const onDownloadProgress = console.log;
const onUploadProgress = console.log;
rembg({
    apiKey: API_KEY,
    inputImage: './input.png', //inputImage can be one of these: string | Buffer | { base64: string };
    onDownloadProgress,
    onUploadProgress
}).then(({ outputImagePath, cleanup }) => {
    console.log('✅🎉 background removed and saved under path=', outputImagePath);
    // if called, it will cleanup (remove from disk) your removed background image
    // cleanup();
});
					
						

Rețineți că funcția de curățare poate fi apelată dacă doriți să eliminați imaginea procesată de pe disc după îndepărtarea fundalului.

Se afișează bara de progres

Când integrați un serviciu de eliminare a fundalului, este adesea benefic să oferiți utilizatorilor feedback cu privire la progresul solicitării lor de încărcare sau descărcare. Pentru a facilita acest lucru, puteți defini propriile apeluri onDownloadProgress și onUploadProgress. Ambele apeluri inverse acceptă AxiosProgressEvent ca parametru de eveniment. Pe măsură ce cererea continuă, aceste apeluri inverse sunt invocate de mai multe ori, permițându-vă, de exemplu, să afișați o bară de progres și să ajustați lungimea acesteia în funcție de progres.


 (base) root@DESKTOP-C0Q8KK7:~/rembg.js-test# node index.mjs
 {
   loaded: 65687,
   total: 68474,
   progress: 0.9592984198381868, <---- @95% progress 
   bytes: 65687,
   rate: undefined,
   estimated: undefined,
   upload: true  <---- upload progress
 }
 {
   loaded: 68474,
   total: 68474,
   progress: 1, <---- @100% progress 
   bytes: 2787,
   rate: undefined,
   estimated: undefined,
   upload: true <---- upload progress 
 }
 {
   loaded: 1002,
   total: 68824,
   progress: 0.014558874811112402, <---- @1% progress 
   bytes: 1002,
   rate: undefined,
   estimated: undefined,
   download: true <---- download progress 
 }
 {
   loaded: 68824,
   total: 68824,
   progress: 1, <---- @100% progress 
   bytes: 67822,
   rate: undefined,
   estimated: undefined,
   download: true <---- download progress
 }
 ✅🎉 background removed and saved under path=/tmp/rembg--3339-DBqqeJ2eOs4D-.png
					

Utilizarea calității de membru și a creditelor

Returnează eticheta planului, soldurile creditelor incluse și preplătite și utilizarea. Puteți efectua interogări în funcție de luna calendaristică UTC (veche), după perioada de facturare aliniată la Stripe (pentru monitorizare prin reînnoire) sau puteți enumera perioadele de facturare cunoscute. Autentificați-vă numai cu cheia dvs. API.

Pentru scheme, exemple și o consolă de încercare, vedeți același punct final în referința completă: Deschideți documentele API

Punct final
GET https://www.rembg.com/api/membership-usage
Autentificare

Trimiteți cheia dvs. API: header x-api-key: YOUR_API_KEY_HERE (creați și gestionați cheile în profilul dvs. pe rembg.com).

Parametri de interogare
ParametruTastațiDescriere
yearnumberAn calendaristic (1–9999). Cu luna, citește cheile Redis user:{uid}:app_usage:{year}:{month}. Dacă este omis (și periodStartUnix nu este utilizat), este implicit anul UTC curent.
monthnumber (1–12)Luna calendaristică 1–12 (convenția UTC folosită pentru chei). Dacă este omisă, valoarea implicită este luna UTC curentă.
periodStartUnixnumberMarcaj temporal Unix în secunde: începerea unei ferestre de facturare. Citește user:{uid}:app_usage:cycle:{periodStartUnix} și api_usage:cycle:…. Nu poate fi combinat cu anul sau luna.
expandstringSteaguri separate prin virgulă. Includeți billing_cycle pentru a adăuga un obiect billingCycle: perioada curentă Stripe când billing_period_* există în Redis, altfel luna calendaristică UTC curentă. Funcționează și cu periodStartUnix pentru o anumită fereastră.
includeBillingCycle1 / trueLa fel ca extinderea care conține billing_cycle: setată la 1 sau true pentru a include obiectul billingCycle.
listBillingCycles1 / trueModul dedicat: listBillingCycles=1 sau true returnează numai { billingCycles: [...] }. Scanează Redis pentru cheile de ciclu pentru acest utilizator; alți parametri de interogare sunt ignorați în această solicitare.

Nu treceți periodStartUnix împreună cu anul sau luna — API-ul returnează 400. Modul listBillingCycles este separat și ignoră alți parametri.

Listează perioadele de facturare

Folosiți-l pentru a completa o listă derulantă cu ferestrele de abonament trecute și actuale (fiecare intrare este un periodStartUnix pe care îl puteți transmite cu periodStartUnix=…). Sunt deduse orele de sfârșit ale perioadei (începutul următoarei perioade - 1 sau Stripe current_period_end pentru perioada activă).

curl --location 'https://www.rembg.com/api/membership-usage?listBillingCycles=1' \
  --header 'x-api-key: YOUR_API_KEY_HERE'

Exemplu de răspuns

{
  "billingCycles": [
    {
      "periodStartUnix": 1774268612,
      "periodEndUnix": 1776947012,
      "appUsage": 120,
      "apiUsage": 880
    }
  ]
}

Prima perioadă a fost sortată cea mai nouă. Apare o perioadă dacă există o cheie de utilizare a ciclului sau dacă este billing_period_start curent din webhook-urile Stripe.

Obiectul billingCycle

Prezent atunci când expand includes billing_cycle sau includeBillingCycle este setat. Folosiți-l pentru tablouri de bord: limită de reînnoire, utilizare în fereastră și credite incluse rămase.

CâmpDescriere
periodStartUnixÎnceputul ferestrei de facturare (unix secunde). Se potrivește cu Stripe current_period_start când contul este sincronizat.
periodEndUnixSfârșitul ferestrei curente (unix secunde), adică chiar înainte de următoarea reînnoire — Stripe current_period_end când este sincronizat. Nu este aceeași cu data de anulare a abonamentului.
appUsage / apiUsageUtilizarea creditului inclus este contorizată în această fereastră: web/editor (aplicație) vs cheie API (api). usedIncludedCredits este egal cu suma lor.
includedCreditsAlocația de credit inclusă (plan) așa cum este stocată în Redis (aceeași idee ca și creditele de nivel superior).
prepaidCreditsSold preplătit (achiziționat); nu resetează fiecare perioadă de facturare.
usedIncludedCreditsUtilizarea totală inclusă în fereastră (aplicație + API). Consumul preplătit nu este adăugat aici.
remainingIncludedCreditsmax(0, inclusivCredits − usedIncludedCredits) pentru acest instantaneu.
stripeBillingSyncedadevărat atunci când Redis are billing_period_start/end de la Stripe, astfel încât fereastra să se potrivească cu abonamentul dvs.; false înseamnă că API-ul a scăzut la o lună calendaristică UTC pentru acest bloc.

Până când webhook-urile Stripe au scris perioade de facturare pentru utilizator, stripeBillingSynced poate fi fals, iar fereastra BillingCycle urmează luna calendaristică UTC. După sincronizare, limitele de utilizare ale API-ului de imagine se aliniază cu aceleași taste de ciclu.

Pentru „creditele utilizate înainte de următoarea reînnoire”, apelați cu expand=billing_cycle și utilizați billingCycle.periodEndUnix ca limită de reînnoire, billingCycle.usedIncludedCredits (sau appUsage + apiUsage) și billingCycle.remainingIncludedCredits. Adăugați credite preplătite dacă doriți soldul total disponibil.

Exemple (cURL)

Utilizare pentru o anumită lună calendaristică UTC

curl --location 'https://www.rembg.com/api/membership-usage?year=2026&month=3' \
  --header 'x-api-key: YOUR_API_KEY_HERE'

Ciclul de facturare curent + Blocarea ciclului de facturare completă (aliniat la reînnoire când este sincronizat)

# Current subscription window + usage (renewal-aligned when Stripe is synced)
curl --location 'https://www.rembg.com/api/membership-usage?expand=billing_cycle' \
  --header 'x-api-key: YOUR_API_KEY_HERE'

O fereastră istorică de facturare la începutul perioadei (din listBillingCycles sau Stripe)

# Specific billing period by Stripe period start (unix seconds)
curl --location 'https://www.rembg.com/api/membership-usage?periodStartUnix=1774268612&expand=billing_cycle' \
  --header 'x-api-key: YOUR_API_KEY_HERE'
Exemplu JSON (cu ciclu de facturare)

App_usage și api_usage de nivel superior reflectă întotdeauna fie luna calendaristică solicitată, fie, atunci când periodStartUnix este setat, contoarele ciclului respectiv. Când expand=billing_cycle este omis, billingCycle este absent.

{
  "membership": "Premium-20000",
  "credits": 18500,
  "prepaidCredits": 2000,
  "app_usage": 8500,
  "api_usage": 10000,
  "billingCycle": {
    "periodStartUnix": 1740441600,
    "periodEndUnix": 1743033599,
    "appUsage": 4200,
    "apiUsage": 5100,
    "includedCredits": 18500,
    "prepaidCredits": 2000,
    "usedIncludedCredits": 9300,
    "remainingIncludedCredits": 9200,
    "stripeBillingSynced": true
  }
}

Când stripeBillingSynced este adevărat, billingCycle se potrivește cu aplicarea din API-ul pentru eliminarea fundalului. Când este fals, bazați-vă pe câmpurile lunii calendaristice sau așteptați până când webhook-urile populează billing_period_* în Redis.

Error Responses

All error responses return a JSON body with a status field matching the HTTP status code.

Single Error Response

HTTP/1.1 400 Bad Request

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Image width (12000px) exceeds the maximum allowed width of 10000px.",
  "field": "image",
  "status": 400
}

HTTP/1.1 400 Bad Request

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Multiple validation errors",
  "details": [
    { "field": "w", "message": "'w' must be an integer, got: 'abc'" },
    { "field": "angle", "message": "'angle' must be between -360 and 360 degrees, got: 500.0" }
  ],
  "status": 400
}
Error Reference
ScenarioStatusError Message
No image provided
400
No image file provided. Please include an 'image' field in your form data.
No file selected
400
No file selected. Please choose an image file to upload.
Unsupported file type
400
File type '.exe' is not supported. Allowed formats: webp, bmp, png, jpg, jpeg
Corrupt image
400
File does not appear to be a valid image (invalid file signature)
Empty file (0 bytes)
400
Uploaded file is empty (0 bytes).
File too large
400
File size (55.2 MB) exceeds the maximum allowed size of 50 MB.
Image too wide
400
Image width (12000px) exceeds the maximum allowed width of 10000px.
Image too tall
400
Image height (15000px) exceeds the maximum allowed height of 10000px.
Bad w or h value
400
'w' must be an integer, got: 'abc'
w or h out of range
400
'w' must be at least 1, got: -5
w or h above max
400
'w' must be at most 10000, got: 15000
Bad angle
400
'angle' must be a number, got: 'ninety'
Angle out of range
400
'angle' must be between -360 and 360 degrees, got: 500.0
Bad output format
400
Invalid format 'gif'. Allowed formats: PNG, JPEG, WEBP, BMP
Bad bg_color
400
Invalid color format '#12345'. Use hex format: #RGB, #RGBA, #RRGGBB, or #RRGGBBAA
mask + bg_color conflict
400
Cannot use 'mask=true' together with 'bg_color'. Choose one or the other.
Email not verified
403
Email address not verified – please check your inbox
Invalid API key
401
invalid api key
Both API key and user token sent
400
This is a mistake: Cannot use both API key and user token
Rate limit exceeded (short-term)
429
You're making requests too quickly, Please Upgrade or slow down.
Rate limit exceeded (daily, anonymous)
429
You've reached your daily limit. Please sign up for more access.
Rate limit exceeded (monthly, authenticated)
429
You've reached your monthly limit. Consider purchasing more credits.
Error Handling Guidelines
  • Check HTTP status code 400 to identify validation errors
  • Parse the error field for the error message
  • Check for the details array when handling multiple validation errors
  • Use the field property to map errors to specific request parameters