RemBG Background Removal API – Docs ng Developer at Gabay sa Pagsasama
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 sanggunianPag-install ng 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") |
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
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)
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-usageAuthentication
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
| Parameter | Uri | Paglalarawan |
|---|---|---|
| year | number | Taon 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. |
| month | number (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. |
| periodStartUnix | number | Unix 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. |
| expand | string | Mga 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. |
| includeBillingCycle | 1 / true | Kapareho ng expand na naglalaman ng billing_cycle: itinakda sa 1 o true upang isama ang object ng billingCycle. |
| listBillingCycles | 1 / true | Dedicated 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.
| Field | Paglalarawan |
|---|---|
| periodStartUnix | Simula ng window ng pagsingil (unix seconds). Tumutugma sa Stripe current_period_start kapag naka-sync ang account. |
| periodEndUnix | Katapusan 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 / apiUsage | Binibilang ang paggamit ng kasamang credit sa window na ito: web/editor (app) vs API key (api). usedIncludedCredits ay katumbas ng kanilang kabuuan. |
| includedCredits | Ang iyong kasamang (plano) na credit allowance na nakaimbak sa Redis (kapareho ng ideya ng mga nangungunang antas ng kredito). |
| prepaidCredits | Prepaid (binili) na balanse; hindi nire-reset ang bawat panahon ng pagsingil. |
| usedIncludedCredits | Kabuuang kasamang paggamit sa window (app + API). Ang prepaid consumption ay hindi idinaragdag dito. |
| remainingIncludedCredits | max(0, includedCredits − usedIncludedCredits) para sa snapshot na ito. |
| stripeBillingSynced | true 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.
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