RemBG Background Removal API – Documente pentru dezvoltatori și Ghid de integrare
Explorați API-ul complet — rulați solicitări reale în browserul dvs.
Răsfoiți fiecare punct final, parametri și răspunsuri. Încercați solicitările cu cheia API, apoi obțineți oricând specificația brută de la /api/openapi.
Lansați referința interactivăInstalarea 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") |
Configurarea mediului: Asigurați-vă că aveți un fișier .env în rădăcina proiectului dvs. care conține cheia dvs. API.
Importarea modulelor necesare: Începeți prin a importa funcția rembg din @remove-background-ai/rembg.js și modulul dotenv pentru a gestiona variabilele de mediu.
Configurarea apelurilor de progres: Biblioteca oferă apeluri onDownloadProgress și onUploadProgress pentru a urmări progresul operațiunilor cu fișiere. În exemplul oferit, înregistrăm aceste evenimente direct în consolă.
Acum, să aruncăm o privire mai atentă la un exemplu de utilizare:
// 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();
});
Rețineți că funcția de curățare poate fi apelată dacă doriți să eliminați imaginea procesată de pe disc după îndepărtarea fundalului.
Se afișează bara de progres
Când integrați un serviciu de eliminare a fundalului, este adesea benefic să oferiți utilizatorilor feedback cu privire la progresul solicitării lor de încărcare sau descărcare. Pentru a facilita acest lucru, puteți defini propriile apeluri onDownloadProgress și onUploadProgress. Ambele apeluri inverse acceptă AxiosProgressEvent ca parametru de eveniment. Pe măsură ce cererea continuă, aceste apeluri inverse sunt invocate de mai multe ori, permițându-vă, de exemplu, să afișați o bară de progres și să ajustați lungimea acesteia în funcție de progres.
(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)
Utilizarea calității de membru și a creditelor
Returnează eticheta planului, soldurile creditelor incluse și preplătite și utilizarea. Puteți efectua interogări în funcție de luna calendaristică UTC (veche), după perioada de facturare aliniată la Stripe (pentru monitorizare prin reînnoire) sau puteți enumera perioadele de facturare cunoscute. Autentificați-vă numai cu cheia dvs. API.
Pentru scheme, exemple și o consolă de încercare, vedeți același punct final în referința completă: Deschideți documentele API
Punct final
GET https://www.rembg.com/api/membership-usageAutentificare
Trimiteți cheia dvs. API: header x-api-key: YOUR_API_KEY_HERE (creați și gestionați cheile în profilul dvs. pe rembg.com).
Parametri de interogare
| Parametru | Tastați | Descriere |
|---|---|---|
| year | number | An calendaristic (1–9999). Cu luna, citește cheile Redis user:{uid}:app_usage:{year}:{month}. Dacă este omis (și periodStartUnix nu este utilizat), este implicit anul UTC curent. |
| month | number (1–12) | Luna calendaristică 1–12 (convenția UTC folosită pentru chei). Dacă este omisă, valoarea implicită este luna UTC curentă. |
| periodStartUnix | number | Marcaj temporal Unix în secunde: începerea unei ferestre de facturare. Citește user:{uid}:app_usage:cycle:{periodStartUnix} și api_usage:cycle:…. Nu poate fi combinat cu anul sau luna. |
| expand | string | Steaguri separate prin virgulă. Includeți billing_cycle pentru a adăuga un obiect billingCycle: perioada curentă Stripe când billing_period_* există în Redis, altfel luna calendaristică UTC curentă. Funcționează și cu periodStartUnix pentru o anumită fereastră. |
| includeBillingCycle | 1 / true | La fel ca extinderea care conține billing_cycle: setată la 1 sau true pentru a include obiectul billingCycle. |
| listBillingCycles | 1 / true | Modul dedicat: listBillingCycles=1 sau true returnează numai { billingCycles: [...] }. Scanează Redis pentru cheile de ciclu pentru acest utilizator; alți parametri de interogare sunt ignorați în această solicitare. |
Nu treceți periodStartUnix împreună cu anul sau luna — API-ul returnează 400. Modul listBillingCycles este separat și ignoră alți parametri.
Listează perioadele de facturare
Folosiți-l pentru a completa o listă derulantă cu ferestrele de abonament trecute și actuale (fiecare intrare este un periodStartUnix pe care îl puteți transmite cu periodStartUnix=…). Sunt deduse orele de sfârșit ale perioadei (începutul următoarei perioade - 1 sau Stripe current_period_end pentru perioada activă).
curl --location 'https://www.rembg.com/api/membership-usage?listBillingCycles=1' \ --header 'x-api-key: YOUR_API_KEY_HERE'
Exemplu de răspuns
{
"billingCycles": [
{
"periodStartUnix": 1774268612,
"periodEndUnix": 1776947012,
"appUsage": 120,
"apiUsage": 880
}
]
}Prima perioadă a fost sortată cea mai nouă. Apare o perioadă dacă există o cheie de utilizare a ciclului sau dacă este billing_period_start curent din webhook-urile Stripe.
Obiectul billingCycle
Prezent atunci când expand includes billing_cycle sau includeBillingCycle este setat. Folosiți-l pentru tablouri de bord: limită de reînnoire, utilizare în fereastră și credite incluse rămase.
| Câmp | Descriere |
|---|---|
| periodStartUnix | Începutul ferestrei de facturare (unix secunde). Se potrivește cu Stripe current_period_start când contul este sincronizat. |
| periodEndUnix | Sfârșitul ferestrei curente (unix secunde), adică chiar înainte de următoarea reînnoire — Stripe current_period_end când este sincronizat. Nu este aceeași cu data de anulare a abonamentului. |
| appUsage / apiUsage | Utilizarea creditului inclus este contorizată în această fereastră: web/editor (aplicație) vs cheie API (api). usedIncludedCredits este egal cu suma lor. |
| includedCredits | Alocația de credit inclusă (plan) așa cum este stocată în Redis (aceeași idee ca și creditele de nivel superior). |
| prepaidCredits | Sold preplătit (achiziționat); nu resetează fiecare perioadă de facturare. |
| usedIncludedCredits | Utilizarea totală inclusă în fereastră (aplicație + API). Consumul preplătit nu este adăugat aici. |
| remainingIncludedCredits | max(0, inclusivCredits − usedIncludedCredits) pentru acest instantaneu. |
| stripeBillingSynced | adevărat atunci când Redis are billing_period_start/end de la Stripe, astfel încât fereastra să se potrivească cu abonamentul dvs.; false înseamnă că API-ul a scăzut la o lună calendaristică UTC pentru acest bloc. |
Până când webhook-urile Stripe au scris perioade de facturare pentru utilizator, stripeBillingSynced poate fi fals, iar fereastra BillingCycle urmează luna calendaristică UTC. După sincronizare, limitele de utilizare ale API-ului de imagine se aliniază cu aceleași taste de ciclu.
Pentru „creditele utilizate înainte de următoarea reînnoire”, apelați cu expand=billing_cycle și utilizați billingCycle.periodEndUnix ca limită de reînnoire, billingCycle.usedIncludedCredits (sau appUsage + apiUsage) și billingCycle.remainingIncludedCredits. Adăugați credite preplătite dacă doriți soldul total disponibil.
Exemple (cURL)
Utilizare pentru o anumită lună calendaristică UTC
curl --location 'https://www.rembg.com/api/membership-usage?year=2026&month=3' \ --header 'x-api-key: YOUR_API_KEY_HERE'
Ciclul de facturare curent + Blocarea ciclului de facturare completă (aliniat la reînnoire când este sincronizat)
# 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'
O fereastră istorică de facturare la începutul perioadei (din listBillingCycles sau 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'
Exemplu JSON (cu ciclu de facturare)
App_usage și api_usage de nivel superior reflectă întotdeauna fie luna calendaristică solicitată, fie, atunci când periodStartUnix este setat, contoarele ciclului respectiv. Când expand=billing_cycle este omis, billingCycle este absent.
{
"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
}
}Când stripeBillingSynced este adevărat, billingCycle se potrivește cu aplicarea din API-ul pentru eliminarea fundalului. Când este fals, bazați-vă pe câmpurile lunii calendaristice sau așteptați până când webhook-urile populează billing_period_* în 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