RemBG API voor achtergrondverwijdering – Documenten voor ontwikkelaars en integratiehandleiding
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 startenInstallatie van rembg.js
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
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| apiKey | string | Required | – | Your Rembg API key |
| inputImage | string | 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.format | webp (default) | png | Optional | webp | Specifies the output image format. Either "webp" (default) or "png" |
| options.returnBase64 | boolean | Optional | false | Return Base64 string instead of file |
| options.returnMask | boolean | Optional | false | Return only the alpha mask |
| options.w | number | Optional | – | Target width (maintains aspect ratio) |
| options.h | number | Optional | – | Target height (maintains aspect ratio) |
| options.exact_resize | boolean | Optional | false | Force exact width × height (may distort) |
| options.angle | number | Optional | 0 | Rotation angle in degrees |
| options.expand | boolean | Optional | true | Add padding so rotated images aren’t cropped |
| options.bg_color | string | 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
Curl
# Full example: upload an image and remove its background with all optional parameters curl -X POST "https://api.rembg.com/rmbg" -H "x-api-key: YOUR_API_KEY_HERE" # your personal API key -F "image=@/path/to/image.jpg" # input image file -F "format=webp" # output format: webp (default) or png -F "w=800" # target width in pixels (maintains aspect ratio unless exact_resize=true) -F "h=600" # target height in pixels -F "exact_resize=false" # true = force exact w × h, may distort -F "mask=false" # true = return only the alpha mask instead of full image -F "bg_color=#ffffffff" # optional solid background color (RGBA hex) -F "angle=0" # rotate the image by given degrees after processing -F "expand=true" # add padding so rotated images don’t get cropped
HTTP
POST /rmbg HTTP/1.1
Host: api.rembg.com
x-api-key: YOUR_API_KEY_HERE
Content-Type: multipart/form-data; boundary=----BOUNDARY
------BOUNDARY
Content-Disposition: form-data; name="image"; filename="image.jpg"
Content-Type: image/jpeg
<binary data of your image goes here>
------BOUNDARY
Content-Disposition: form-data; name="format"
webp
------BOUNDARY
Content-Disposition: form-data; name="w"
800
------BOUNDARY
Content-Disposition: form-data; name="h"
600
------BOUNDARY
Content-Disposition: form-data; name="exact_resize"
false
------BOUNDARY
Content-Disposition: form-data; name="mask"
false
------BOUNDARY
Content-Disposition: form-data; name="bg_color"
#ffffffff
------BOUNDARY
Content-Disposition: form-data; name="angle"
0
------BOUNDARY
Content-Disposition: form-data; name="expand"
true
------BOUNDARY--
Python Requests
import requests
# Endpoint URL for the background-removal API
url = "https://api.rembg.com/rmbg"
# Required API key header
headers = {
"x-api-key": "YOUR_API_KEY_HERE"
}
# The image file to process (opened in binary mode)
files = {
"image": open("/path/to/image.jpg", "rb")
}
# Optional form fields supported by your backend.
# Adjust values as needed; any of these can be omitted.
data = {
"format": "webp", # Output format: "webp" (default) or "png"
"w": 800, # Target width (maintains aspect ratio unless exact_resize is true)
"h": 600, # Target height
"exact_resize": "false", # "true" forces exact w×h, may distort
"mask": "false", # "true" returns only the alpha mask
"bg_color": "#ffffffff", # Optional solid background color (RGBA hex)
"angle": 0, # Rotation angle in degrees
"expand": "true", # Add padding so rotated images aren’t cropped
}
# Send the POST request with headers, file, and extra form data
response = requests.post(url, headers=headers, files=files, data=data)
# Handle the response
if response.status_code == 200:
# Save the processed image to disk
with open("output.webp", "wb") as f:
f.write(response.content)
print("Background removed successfully → saved as output.webp")
else:
# Print error details if the request failed
print("Error:", response.status_code, response.text)
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-usageAuthenticatie
Verzend uw API-sleutel: header x-api-key: YOUR_API_KEY_HIER (maak en beheer sleutels in uw profiel op rembg.com).
Queryparameters
| Parameter | Typ | Beschrijving |
|---|---|---|
| year | number | Kalenderjaar (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. |
| month | number (1–12) | Kalendermaand 1–12 (UTC-conventie gebruikt voor sleutels). Indien dit wordt weggelaten, wordt standaard de huidige UTC-maand gebruikt. |
| periodStartUnix | number | Unix-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. |
| expand | string | Door 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. |
| includeBillingCycle | 1 / true | Hetzelfde als expand met billing_cycle: stel deze in op 1 of true om het object billingCycle op te nemen. |
| listBillingCycles | 1 / true | Speciale 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.
| Veld | Beschrijving |
|---|---|
| periodStartUnix | Begin van het facturatievenster (unix-seconden). Komt overeen met Stripe current_period_start wanneer het account is gesynchroniseerd. |
| periodEndUnix | Einde 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 / apiUsage | Gebruik van inbegrepen tegoeden geteld in dit venster: web/editor (app) versus API-sleutel (api). usedIncludedCredits is gelijk aan hun som. |
| includedCredits | Uw inbegrepen (plan)tegoed zoals opgeslagen in Redis (hetzelfde idee als tegoeden op het hoogste niveau). |
| prepaidCredits | Prepaid (aangekocht) saldo; reset niet elke factureringsperiode. |
| usedIncludedCredits | Totaal inbegrepen gebruik in het venster (app + API). Het prepaid-verbruik is hier niet bijgeteld. |
| remainingIncludedCredits | max(0, includingCredits − usedIncludedCredits) voor deze momentopname. |
| stripeBillingSynced | waar 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.
Multiple Validation Errors Response
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
| Scenario | Status | Error 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
errorfield for the error message - Check for the
detailsarray when handling multiple validation errors - Use the
fieldproperty to map errors to specific request parameters