RemBG Background Removal API – Utvecklardokument och integrationsguide






OpenAPI · Live lekplats

Utforska hela API:et – kör riktiga förfrågningar i din webbläsare

Bläddra igenom alla slutpunkter, parametrar och svar. Prova förfrågningar med din API-nyckel och ta sedan den råa specen på /api/openapi när som helst.

Starta interaktiv referens

Installation av 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")
  • Konfigurera din miljö: Se till att du har en .env-fil i din projektrot som innehåller din API-nyckel.

  • Importera de nödvändiga modulerna: Börja med att importera rembg-funktionen från @remove-background-ai/rembg.js och dotenv-modulen för att hantera miljövariabler.

  • Konfigurera Progress Callbacks: Biblioteket erbjuder onDownloadProgress och onUploadProgress callbacks för att spåra förloppet för filoperationer. I det angivna exemplet loggar vi dessa händelser direkt till konsolen.

Låt oss nu titta närmare på ett exempel på användning:


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

Kom ihåg att rensningsfunktionen kan anropas om du vill ta bort den bearbetade bilden från din disk efter borttagning av bakgrunden.

Visar förloppsindikator

När man integrerar en bakgrundsborttagningstjänst är det ofta fördelaktigt att ge användarna feedback om hur deras uppladdnings- eller nedladdningsförfrågan fortskrider. För att underlätta detta kan du definiera dina egna onDownloadProgress och onUploadProgress callbacks. Båda dessa callbacks accepterar AxiosProgressEvent som en händelseparameter. När förfrågan fortskrider anropas dessa återuppringningar flera gånger, vilket gör att du till exempel kan visa en förloppsindikator och justera dess längd baserat på förloppet.


 (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
					

Användning av medlemskap och krediter

Returnerar din planetikett, inkluderade och förbetalda kreditsaldon och användning. Du kan fråga efter UTC-kalendermånad (legacy), efter Stripe-aligned faktureringsperiod (för övervakning genom förnyelse) eller lista kända faktureringsperioder. Autentisera endast med din API-nyckel.

För scheman, exempel och en prova-det-konsol, se samma slutpunkt i den fullständiga referensen: Öppna API-dokument

Slutpunkt
GET https://www.rembg.com/api/membership-usage
Autentisering

Skicka din API-nyckel: header x-api-key: YOUR_API_KEY_HERE (skapa och hantera nycklar i din profil på rembg.com).

Frågeparametrar
ParameterTypBeskrivning
yearnumberKalenderår (1–9999). Med månad står Redis keys user:{uid}:app_usage:{year}:{month}. Om den utelämnas (och periodStartUnix inte används), är standardinställningen aktuellt UTC-år.
monthnumber (1–12)Kalendermånad 1–12 (UTC-konvention används för nycklar). Om den utelämnas, används som standard till aktuell UTC-månad.
periodStartUnixnumberUnix-tidsstämpel i sekunder: start av ett faktureringsfönster. Läser användare:{uid}:app_usage:cycle:{periodStartUnix} och api_usage:cycle:…. Kan ej kombineras med år eller månad.
expandstringKommaseparerade flaggor. Inkludera billing_cycle för att lägga till ett billingCycle-objekt: aktuell Stripe-period när billing_period_* finns i Redis, annars den aktuella UTC-kalendermånaden. Fungerar även med periodStartUnix för ett specifikt fönster.
includeBillingCycle1 / trueSamma som expand som innehåller billing_cycle: ställ in på 1 eller true för att inkludera billingCycle-objektet.
listBillingCycles1 / trueDedikerat läge: listBillingCycles=1 eller true returnerar endast { billingCycles: [...] }. Skannar Redis efter cykelnycklar för denna användare; andra frågeparametrar ignoreras på denna begäran.

Passera inte periodStartUnix tillsammans med år eller månad — API:et returnerar 400. ListBillingCycles-läget är separat och ignorerar andra parametrar.

Lista faktureringsperioder

Använd detta för att fylla i en rullgardinsmeny med tidigare och nuvarande prenumerationsfönster (varje post är en periodStartUnix som du kan skicka tillbaka med periodStartUnix=...). Periodens sluttider härleds (start för nästa period − 1, eller Stripe current_period_end för den aktiva perioden).

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

Exempelsvar

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

Sorterade den senaste perioden först. En period visas om det finns en cykelanvändningsnyckel eller om det är den aktuella billing_period_start från Stripe webhooks.

billingCycle-objektet

Finns när expand inkluderar billing_cycle eller includeBillingCycle är inställd. Använd den för instrumentpaneler: förnyelsegräns, användning i fönstret och återstående inkluderade krediter.

FältBeskrivning
periodStartUnixStart av faktureringsfönstret (unix sekunder). Matchar Stripe current_period_start när kontot synkroniseras.
periodEndUnixSlut på det aktuella fönstret (unix sekunder), dvs strax före nästa förnyelse — Stripe current_period_end när den synkroniseras. Inte samma som datum för uppsägning av prenumeration.
appUsage / apiUsageInkluderad kreditanvändning räknas i detta fönster: webb/redigerare (app) kontra API-nyckel (api). usedIncludedCredits är lika med deras summa.
includedCreditsDin inkluderade (planerade) kreditavdrag som lagras i Redis (samma idé som krediter på toppnivå).
prepaidCreditsFörbetalt (köpt) saldo; återställer inte varje faktureringsperiod.
usedIncludedCreditsTotalt inkluderat användning i fönstret (app + API). Förutbetald förbrukning läggs inte till här.
remainingIncludedCreditsmax(0, includedCredits − usedIncludedCredits) för denna ögonblicksbild.
stripeBillingSyncedsant när Redis har billing_period_start/end från Stripe så att fönstret matchar ditt abonnemang; false betyder att API:et föll tillbaka till en UTC-kalendermånad för detta block.

Tills Stripe webhooks har skrivit faktureringsperioder för användaren kan stripeBillingSynced vara falskt och faktureringscykelfönstret följer UTC-kalendermånaden. Efter synkronisering anpassas användningsgränserna för bild-API:t med samma cykelnycklar.

För "krediter som används före nästa förnyelse", ring med expand=billing_cycle och använd billingCycle.periodEndUnix som förnyelsegräns, billingCycle.usedIncludedCredits (eller appUsage + apiUsage) och billingCycle.remainingIncludedCredits. Lägg till prepaidCredits om du vill ha totalt disponibelt saldo.

Exempel (cURL)

Användning för en specifik UTC-kalendermånad

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

Aktuell faktureringscykel + fullständig faktureringscykelblock (förnyelsejusterad vid synkronisering)

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

Ett historiskt faktureringsfönster per periodstart (från listBillingCycles eller 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'
Exempel JSON (med faktureringscykel)

App_usage och api_usage på toppnivå återspeglar alltid antingen den begärda kalendermånaden eller, när periodStartUnix är inställd, den cykelns räknare. När expand=billing_cycle utelämnas saknas billingCycle.

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

När stripeBillingSynced är sant matchar billingCycle tillämpningen av API:et för bakgrundsborttagning. Om det är falskt, lita på kalendermånadsfält eller vänta tills webhooks fyller i billing_period_* i 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