RemBG Background Removal API – utviklerdokumenter og integreringsveiledning

OpenAPI · Live-lekeplass

Utforsk hele API-en – kjør ekte forespørsler i nettleseren din

Bla gjennom alle endepunkter, parametere og svar. Prøv forespørsler med API-nøkkelen din, og hent den rå spesifikasjonen på /api/openapi når som helst.

Start interaktiv referanse

Installasjon av 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")

Sette opp miljøet ditt: Sørg for at du har en .env-fil i prosjektroten som inneholder API-nøkkelen.
Importere de nødvendige modulene: Begynn med å importere rembg-funksjonen fra @remove-background-ai/rembg.js og dotenv-modulen for å håndtere miljøvariabler.
Konfigurering av fremskritts tilbakeringinger: Biblioteket tilbyr onDownloadProgress og onUploadProgress tilbakeringinger for å spore fremdriften av filoperasjoner. I det angitte eksemplet logger vi disse hendelsene direkte til konsollen.

La oss nå se nærmere på et eksempelbruk:


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

Husk at oppryddingsfunksjonen kan kalles hvis du ønsker å fjerne det behandlede bildet fra disken etter fjerning av bakgrunnen.

Viser fremdriftslinje

Når du integrerer en tjeneste for fjerning av bakgrunn, er det ofte fordelaktig å gi brukere tilbakemelding om fremdriften til opplastings- eller nedlastingsforespørselen. For å lette dette kan du definere dine egne onDownloadProgress og onUploadProgress tilbakeringinger. Begge disse tilbakeringingene aksepterer AxiosProgressEvent som en hendelsesparameter. Etter hvert som forespørselen fortsetter, blir disse tilbakeringingene påkalt flere ganger, slik at du for eksempel kan vise en fremdriftslinje og justere lengden basert på fremdriften.


 (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)

Bruk av medlemskap og kreditter

Returnerer planetiketten, inkludert og forhåndsbetalt kredittsaldo og bruk. Du kan spørre etter UTC-kalendermåned (legacy), etter Stripe-justert faktureringsperiode (for overvåking gjennom fornyelse), eller liste opp kjente faktureringsperioder. Autentiser kun med API-nøkkelen din.

For skjemaer, eksempler og en prøvekonsoll, se det samme endepunktet i den fullstendige referansen: Åpne API-dokumenter

Sluttpunkt

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

Autentisering

Send din API-nøkkel: header x-api-key: YOUR_API_KEY_HERE (opprett og administrer nøkler i profilen din på rembg.com).

Søkeparametere

Parameter	Type	Beskrivelse
year	number	Kalenderår (1–9999). Med måned, står Redis keys user:{uid}:app_usage:{year}:{month}. Hvis den utelates (og periodStartUnix ikke brukes), er standard UTC-år.
month	number (1–12)	Kalendermåned 1–12 (UTC-konvensjon brukt for nøkler). Hvis utelatt, er standard UTC-måned.
periodStartUnix	number	Unix-tidsstempel i sekunder: starten på et faktureringsvindu. Leser bruker:{uid}:app_usage:cycle:{periodStartUnix} og api_usage:cycle:…. Kan ikke kombineres med år eller måned.
expand	string	Kommaseparerte flagg. Inkluder billing_cycle for å legge til et billingCycle-objekt: gjeldende Stripe-periode når billing_period_* eksisterer i Redis, ellers gjeldende UTC-kalendermåned. Fungerer også med periodStartUnix for et spesifikt vindu.
includeBillingCycle	1 / true	Samme som utvidelse som inneholder billing_cycle: satt til 1 eller sann for å inkludere billingCycle-objektet.
listBillingCycles	1 / true	Dedikert modus: listBillingCycles=1 eller true returnerer bare { billingCycles: [...] }. Skanner Redis for syklusnøkler for denne brukeren; andre spørringsparametere ignoreres på denne forespørselen.

Ikke bestå periodStartUnix sammen med år eller måned — API-en returnerer 400. ListBillingCycles-modusen er separat og ignorerer andre parametere.

Vis faktureringsperioder

Bruk dette til å fylle ut en rullegardin av tidligere og nåværende abonnementsvinduer (hver oppføring er en periodStartUnix som du kan sende tilbake med periodStartUnix=...). Periodesluttider utledes (start av neste periode − 1, eller Stripe gjeldende_periode_slutt for den aktive perioden).

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

Eksempelsvar

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

Sortert den nyeste perioden først. En periode vises hvis det er en syklusbruksnøkkel eller hvis det er gjeldende billing_period_start fra Stripe webhooks.

billingCycle-objektet

Tilstede når utvidelse inkluderer billing_cycle eller includeBillingCycle er angitt. Bruk den til dashbord: fornyelsesgrense, bruk i vinduet og gjenværende inkluderte kreditter.

Felt	Beskrivelse
periodStartUnix	Start av faktureringsvinduet (unix sekunder). Matcher Stripe current_period_start når kontoen er synkronisert.
periodEndUnix	Slutt på gjeldende vindu (unix sekunder), dvs. rett før neste fornyelse — Stripe current_period_end når synkronisert. Ikke det samme som kanselleringsdatoen for abonnementet.
appUsage / apiUsage	Inkludert kredittbruk telles i dette vinduet: web/editor (app) vs API-nøkkel (api). usedIncludedCredits er lik summen deres.
includedCredits	Din inkluderte (plan) kredittgodtgjørelse som er lagret i Redis (samme idé som kreditt på toppnivå).
prepaidCredits	Forhåndsbetalt (kjøpt) saldo; tilbakestiller ikke hver faktureringsperiode.
usedIncludedCredits	Totalt inkludert bruk i vinduet (app + API). Forskuddsbetalt forbruk legges ikke til her.
remainingIncludedCredits	max(0, inkluderte kreditter − bruktInkluderte kreditter) for dette øyeblikksbildet.
stripeBillingSynced	sant når Redis har billing_period_start/end fra Stripe slik at vinduet samsvarer med abonnementet ditt; falsk betyr at API-en falt tilbake til en UTC-kalendermåned for denne blokken.

Inntil Stripe webhooks har skrevet faktureringsperioder for brukeren, kan stripeBillingSynced være falsk og billingCycle-vinduet følger UTC-kalendermåneden. Etter synkronisering justeres bruksgrensene på bilde-API-en med de samme syklustastene.

For "kreditter brukt før neste fornyelse", ring med expand=billing_cycle og bruk billingCycle.periodEndUnix som fornyelsesgrense, billingCycle.usedIncludedCredits (eller appUsage + apiUsage) og billingCycle.remainingIncludedCredits. Legg til forhåndsbetalte kreditter hvis du vil ha total disponibel saldo.

Eksempler (cURL)

Bruk for en bestemt UTC-kalendermåned

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

Gjeldende faktureringssyklus + full faktureringssyklusblokk (fornyelsesjustert ved 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 historisk faktureringsvindu etter periodestart (fra 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'

Eksempel JSON (med faktureringssyklus)

Toppnivå app_usage og api_usage reflekterer alltid enten den forespurte kalendermåneden eller, når periodStartUnix er satt, den syklusens tellere. Når expand=billing_cycle er utelatt, er billingCycle fraværende.

{
  "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 er sant, samsvarer billingCycle med håndhevelsen på API for bakgrunnsfjerning. Når falsk, stol på kalendermånedsfelt eller vent til webhooks fyller ut 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
}

Multiple Validation Errors Response