RemBG API voor achtergrondverwijdering – Documenten voor ontwikkelaars en integratiehandleiding






OpenAPI · Live speeltuin

Ontdek de volledige API: voer echte verzoeken uit in uw browser

Blader door alle eindpunten, parameters en reacties. Probeer verzoeken uit met uw API-sleutel en pak vervolgens op elk gewenst moment de onbewerkte specificaties op /api/openapi.

Interactieve referentie starten

Installatie van 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")
  • Uw omgeving instellen: Zorg ervoor dat u een .env-bestand in de hoofdmap van uw project heeft met daarin uw API-sleutel.

  • De benodigde modules importeren: Begin met het importeren van de rembg-functie uit @remove-background-ai/rembg.js en de dotenv-module om omgevingsvariabelen te verwerken.

  • Voortgangsterugbelverzoeken configureren: De bibliotheek biedt onDownloadProgress- en onUploadProgress-callbacks om de voortgang van bestandsbewerkingen bij te houden. In het gegeven voorbeeld registreren we deze gebeurtenissen rechtstreeks op de console.

Laten we nu een voorbeeldgebruik eens nader bekijken:


// 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();
});
					
						

Houd er rekening mee dat de opschoonfunctie kan worden aangeroepen als u de verwerkte afbeelding van uw schijf wilt verwijderen nadat u de achtergrond hebt verwijderd.

Voortgangsbalk tonen

Bij het integreren van een service voor achtergrondverwijdering is het vaak nuttig om gebruikers feedback te geven over de voortgang van hun upload- of downloadverzoek. Om dit te vergemakkelijken, kunt u uw eigen onDownloadProgress- en onUploadProgress-callbacks definiëren. Beide callbacks accepteren AxiosProgressEvent als gebeurtenisparameter. Naarmate het verzoek vordert, worden deze callbacks meerdere keren aangeroepen, waardoor u bijvoorbeeld een voortgangsbalk kunt weergeven en de lengte ervan kunt aanpassen op basis van de voortgang.


 (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
					

Lidmaatschap en tegoedgebruik

Retourneert uw abonnementslabel, inbegrepen en vooruitbetaalde tegoeden en gebruik. U kunt zoeken op UTC-kalendermaand (verouderd), op Stripe-uitgelijnde factureringsperiode (voor monitoring via verlenging) of een lijst maken van bekende factureringsperioden. Authenticeer alleen met uw API-sleutel.

Voor schema's, voorbeelden en een try-it-console raadpleegt u hetzelfde eindpunt in de volledige referentie: API-documenten openen

Eindpunt
GET https://www.rembg.com/api/membership-usage
Authenticatie

Verzend uw API-sleutel: header x-api-key: YOUR_API_KEY_HIER (maak en beheer sleutels in uw profiel op rembg.com).

Queryparameters
ParameterTypBeschrijving
yearnumberKalenderjaar (1–9999). Met maand wordt Redis-sleutels gebruiker:{uid}:app_usage:{year}:{month} gelezen. Als dit wordt weggelaten (en periodStartUnix niet wordt gebruikt), wordt standaard het huidige UTC-jaar gebruikt.
monthnumber (1–12)Kalendermaand 1–12 (UTC-conventie gebruikt voor sleutels). Indien dit wordt weggelaten, wordt standaard de huidige UTC-maand gebruikt.
periodStartUnixnumberUnix-tijdstempel in seconden: start van een facturatieperiode. Leest gebruiker:{uid}:app_usage:cycle:{periodStartUnix} en api_usage:cycle:…. Kan niet worden gecombineerd met jaar of maand.
expandstringDoor komma's gescheiden vlaggen. Voeg billing_cycle toe om een ​​billingCycle-object toe te voegen: huidige Stripe-periode wanneer billing_period_* bestaat in Redis, anders de huidige UTC-kalendermaand. Werkt ook met periodStartUnix voor een specifiek venster.
includeBillingCycle1 / trueHetzelfde als expand met billing_cycle: stel deze in op 1 of true om het object billingCycle op te nemen.
listBillingCycles1 / trueSpeciale modus: listBillingCycles=1 of alleen true retourneert { billingCycles: [...] }. Scant Redis naar cyclussleutels voor deze gebruiker; andere queryparameters worden bij dit verzoek genegeerd.

Geef periodStartUnix niet samen met jaar of maand door: de API retourneert 400. De listBillingCycles-modus is afzonderlijk en negeert andere parameters.

Lijst met factureringsperioden

Gebruik dit om een vervolgkeuzelijst met eerdere en huidige abonnementsvensters in te vullen (elk item is een periodStartUnix die u kunt doorgeven met periodStartUnix=…). Eindtijden van perioden worden afgeleid (begin volgende periode − 1, of Stripe current_period_end voor de actieve periode).

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

Voorbeeldantwoord

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

Nieuwste periode eerst gesorteerd. Er verschijnt een periode als er een cyclusgebruikssleutel is of als dit de huidige billing_period_start van Stripe-webhooks is.

Het billingCycle-object

Aanwezig wanneer uitbreiden omvat factureringscyclus of includeBillingCycle is ingesteld. Gebruik het voor dashboards: verlengingsgrens, gebruik in de periode en resterende inbegrepen credits.

VeldBeschrijving
periodStartUnixBegin van het facturatievenster (unix-seconden). Komt overeen met Stripe current_period_start wanneer het account is gesynchroniseerd.
periodEndUnixEinde van het huidige venster (unix seconden), d.w.z. vlak voor de volgende verlenging — Stripe current_period_end bij synchronisatie. Niet hetzelfde als de opzegdatum van het abonnement.
appUsage / apiUsageGebruik van inbegrepen tegoeden geteld in dit venster: web/editor (app) versus API-sleutel (api). usedIncludedCredits is gelijk aan hun som.
includedCreditsUw inbegrepen (plan)tegoed zoals opgeslagen in Redis (hetzelfde idee als tegoeden op het hoogste niveau).
prepaidCreditsPrepaid (aangekocht) saldo; reset niet elke factureringsperiode.
usedIncludedCreditsTotaal inbegrepen gebruik in het venster (app + API). Het prepaid-verbruik is hier niet bijgeteld.
remainingIncludedCreditsmax(0, includingCredits − usedIncludedCredits) voor deze momentopname.
stripeBillingSyncedwaar wanneer Redis billing_period_start/end van Stripe heeft, zodat het venster overeenkomt met uw abonnement; false betekent dat de API voor dit blok terugviel naar een UTC-kalendermaand.

Totdat Stripe-webhooks factureringsperioden voor de gebruiker hebben geschreven, kan stripeBillingSynced onwaar zijn en volgt het factureringscyclusvenster de UTC-kalendermaand. Na synchronisatie komen de gebruikslimieten op de afbeeldings-API overeen met dezelfde cyclussleutels.

Voor 'tegoeden gebruikt vóór de volgende verlenging' roept u expand=billing_cycle aan en gebruikt u billingCycle.periodEndUnix als verlengingsgrens, billingCycle.usedIncludedCredits (of appUsage + apiUsage) en billingCycle.remainingIncludedCredits. Voeg prepaidCredits toe als u een totaal besteedbaar saldo wilt.

Voorbeelden (cURL)

Gebruik voor een specifieke UTC-kalendermaand

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

Huidige factureringscyclus + volledige factureringscyclusblokkering (verlenging uitgelijnd bij synchronisatie)

# 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'

Eén historische factureringsperiode per periodebegin (uit de lijst BillingCycles of 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'
Voorbeeld JSON (met factureringscyclus)

App_usage en api_usage op het hoogste niveau weerspiegelen altijd de gevraagde kalendermaand of, wanneer periodStartUnix is ingesteld, de tellers van die cyclus. Wanneer expand=billing_cycle wordt weggelaten, is billingCycle afwezig.

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

Wanneer stripeBillingSynced waar is, komt billingCycle overeen met de handhaving op de API voor achtergrondverwijdering. Als dit niet waar is, vertrouw dan op kalendermaandvelden of wacht tot webhooks billing_period_* in Redis invullen.

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