RemBG Background Removal API – Docs ng Developer at Gabay sa Pagsasama






OpenAPI · Live na palaruan

Galugarin ang buong API—magpatakbo ng mga totoong kahilingan sa iyong browser

I-browse ang bawat endpoint, parameter, at tugon. Subukan ang mga kahilingan gamit ang iyong API key, pagkatapos ay kunin ang raw spec sa /api/openapi anumang oras.

Ilunsad ang interactive na sanggunian

Pag-install ng 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")
  • Pagse-set up ng Iyong Kapaligiran: Tiyaking mayroon kang .env file sa root ng iyong proyekto na naglalaman ng iyong API key.

  • Pag-import ng Mga Kinakailangang Module: Magsimula sa pamamagitan ng pag-import ng rembg function mula sa @remove-background-ai/rembg.js at sa dotenv module upang pangasiwaan ang mga variable ng kapaligiran.

  • Pag-configure ng Mga Callback ng Progreso: Nag-aalok ang library ng onDownloadProgress at onUploadProgress callback upang subaybayan ang pag-usad ng mga pagpapatakbo ng file. Sa ibinigay na halimbawa, direktang nilala-log namin ang mga kaganapang ito sa console.

Ngayon, tingnan natin ang isang sample na paggamit:


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

Tandaan, maaaring tawagan ang function ng paglilinis kung gusto mong alisin ang naprosesong imahe mula sa iyong disk pagkatapos alisin ang background.

Ipinapakita ang Progress bar

Kapag nagsasama ng isang serbisyo sa pag-alis ng background, kadalasan ay kapaki-pakinabang na magbigay sa mga user ng feedback sa pag-usad ng kanilang kahilingan sa pag-upload o pag-download. Upang mapadali ito, maaari mong tukuyin ang iyong sariling onDownloadProgress at onUploadProgress callback. Pareho sa mga callback na ito ay tumatanggap ng AxiosProgressEvent bilang isang parameter ng kaganapan. Habang nagpapatuloy ang kahilingan, ang mga callback na ito ay hinihingi nang maraming beses, na nagbibigay-daan sa iyo, halimbawa, na magpakita ng progress bar at isaayos ang haba nito batay sa pag-usad.


 (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
					

Membership at Paggamit ng Mga Kredito

Ibinabalik ang label ng iyong plano, kasama at prepaid na balanse ng credit, at paggamit. Maaari kang mag-query ayon sa buwan ng kalendaryo ng UTC (legacy), ayon sa panahon ng pagsingil na nakahanay sa Stripe (para sa pagsubaybay sa pamamagitan ng pag-renew), o ilista ang mga kilalang panahon ng pagsingil. Magpatotoo gamit ang iyong API key lamang.

Para sa mga schema, halimbawa, at try-it console, tingnan ang parehong endpoint sa buong reference: Buksan ang mga doc ng API

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

Ipadala ang iyong API key: header x-api-key: YOUR_API_KEY_HERE (lumikha at pamahalaan ang mga key sa iyong profile sa rembg.com).

Mga parameter ng query
ParameterUriPaglalarawan
yearnumberTaon ng kalendaryo (1–9999). Sa buwan, binabasa ang Redis keys user:{uid}:app_usage:{year}:{month}. Kung tinanggal (at hindi ginagamit ang periodStartUnix), magiging default sa kasalukuyang taon ng UTC.
monthnumber (1–12)Buwan ng kalendaryo 1–12 (ginagamit na kombensiyon ng UTC para sa mga susi). Kung aalisin, magiging default sa kasalukuyang buwan ng UTC.
periodStartUnixnumberUnix timestamp sa ilang segundo: simula ng isang window ng pagsingil. Binabasa ang user:{uid}:app_usage:cycle:{periodStartUnix} at api_usage:cycle:…. Hindi maaaring pagsamahin sa taon o buwan.
expandstringMga flag na pinaghihiwalay ng kuwit. Isama ang billing_cycle upang magdagdag ng billingCycle object: kasalukuyang Stripe period kapag ang billing_period_* ay umiiral sa Redis, kung hindi, ang kasalukuyang UTC na buwan ng kalendaryo. Gumagana rin sa periodStartUnix para sa isang partikular na window.
includeBillingCycle1 / trueKapareho ng expand na naglalaman ng billing_cycle: itinakda sa 1 o true upang isama ang object ng billingCycle.
listBillingCycles1 / trueDedicated mode: listBillingCycles=1 o true returns lang { billingCycles: [...] }. Ini-scan ang Redis para sa mga cycle key para sa user na ito; iba pang mga parameter ng query ay binabalewala sa kahilingang ito.

Huwag ipasa ang periodStartUnix kasama ang taon o buwan — ang API ay nagbabalik ng 400. Ang listBillingCycles mode ay hiwalay at hindi pinapansin ang iba pang mga param.

Maglista ng mga panahon ng pagsingil

Gamitin ito upang i-populate ang isang dropdown ng nakaraan at kasalukuyang mga window ng subscription (bawat entry ay isang periodStartUnix na maaari mong ibalik gamit ang periodStartUnix=…). Ang mga oras ng pagtatapos ng yugto ay hinuhulaan (susunod na yugto ng simula − 1, o Stripe current_period_end para sa aktibong panahon).

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

Halimbawa ng tugon

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

Inayos muna ang pinakabagong panahon. Lalabas ang isang panahon kung mayroong susi sa paggamit ng cycle o kung ito ang kasalukuyang billing_period_start mula sa Stripe webhooks.

Ang billingCycle object

Ipakita kapag ang expand ay may kasamang billing_cycle o isama angBillingCycle ay nakatakda. Gamitin ito para sa mga dashboard: hangganan ng pag-renew, paggamit sa window, at mga natitirang kasamang credit.

FieldPaglalarawan
periodStartUnixSimula ng window ng pagsingil (unix seconds). Tumutugma sa Stripe current_period_start kapag naka-sync ang account.
periodEndUnixKatapusan ng kasalukuyang window (unix segundo), ibig sabihin, bago ang susunod na pag-renew — Stripe current_period_end kapag naka-sync. Hindi katulad ng petsa ng pagkansela ng subscription.
appUsage / apiUsageBinibilang ang paggamit ng kasamang credit sa window na ito: web/editor (app) vs API key (api). usedIncludedCredits ay katumbas ng kanilang kabuuan.
includedCreditsAng iyong kasamang (plano) na credit allowance na nakaimbak sa Redis (kapareho ng ideya ng mga nangungunang antas ng kredito).
prepaidCreditsPrepaid (binili) na balanse; hindi nire-reset ang bawat panahon ng pagsingil.
usedIncludedCreditsKabuuang kasamang paggamit sa window (app + API). Ang prepaid consumption ay hindi idinaragdag dito.
remainingIncludedCreditsmax(0, includedCredits − usedIncludedCredits) para sa snapshot na ito.
stripeBillingSyncedtrue kapag may billing_period_start/end ang Redis mula sa Stripe para tumugma ang window sa iyong subscription; false ay nangangahulugan na ang API ay bumalik sa isang UTC na buwan ng kalendaryo para sa block na ito.

Hanggang ang mga Stripe webhook ay nakapagsulat ng mga panahon ng pagsingil para sa user, maaaring mali ang stripeBillingSynced at ang window ng billingCycle ay sumusunod sa buwan ng kalendaryo ng UTC. Pagkatapos ng pag-sync, ang mga limitasyon sa paggamit sa image API ay umaayon sa parehong mga cycle key.

Para sa "mga credit na ginamit bago ang susunod na pag-renew", tumawag gamit ang expand=billing_cycle at gamitin ang billingCycle.periodEndUnix bilang hangganan ng pag-renew, billingCycle.usedIncludedCredits (o appUsage + apiUsage), at billingCycle.remainingIncludedCredits. Magdagdag ng prepaidCredit kung gusto mo ng kabuuang disposable na balanse.

Mga Halimbawa (cURL)

Paggamit para sa isang partikular na buwan ng kalendaryo ng UTC

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

Kasalukuyang ikot ng pagsingil + buong pagsingilIkot ng bloke (nakahanay sa pag-renew kapag naka-sync)

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

Isang makasaysayang palugit ng pagsingil ayon sa simula ng panahon (mula sa listBillingCycles o 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'
Halimbawa ng JSON (na may cycle ng pagsingil)

Palaging ipinapakita ng top-level na app_usage at api_usage ang alinman sa hiniling na buwan sa kalendaryo o, kapag nakatakda ang periodStartUnix, ang mga counter ng cycle na iyon. Kapag ang expand=billing_cycle ay tinanggal, ang billingCycle ay wala.

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

Kapag totoo ang stripeBillingSynced, tumutugma ang billingCycle sa pagpapatupad sa background-removal API. Kapag false, umasa sa mga field sa buwan ng kalendaryo o maghintay hanggang sa ma-populate ng mga webhook ang billing_period_* sa 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