RemBG tausta eemaldamise API – arendaja dokumendid ja integreerimisjuhend
Tutvuge kogu API-ga – esitage oma brauseris tõelisi päringuid
Sirvige iga lõpp-punkti, parameetreid ja vastuseid. Proovige taotlusi oma API-võtmega, seejärel hankige igal ajal töötlemata spetsifikatsioon aadressil /api/openapi.
Käivitage interaktiivne viideFaili rembg.js installimine
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") |
Keskkonna seadistamine: Veenduge, et teie projekti juures oleks .env-fail, mis sisaldab teie API-võtit.
Vajalike moodulite importimine: Alustuseks importige keskkonnamuutujate käsitlemiseks funktsioon rembg failist @remove-background-ai/rembg.js ja dotenv moodul.
Edenemise tagasihelistamiste konfigureerimine: Teek pakub onDownloadProgressi ja onUploadProgressi tagasihelistusi, et jälgida failitoimingute edenemist. Esitatud näites logime need sündmused otse konsooli.
Nüüd vaatame lähemalt kasutusnäidist:
// 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();
});
Pidage meeles, et puhastusfunktsiooni saab kutsuda, kui soovite pärast tausta eemaldamist töödeldud pildi oma kettalt eemaldada.
Edenemisriba kuvamine
Taustal eemaldamise teenuse integreerimisel on sageli kasulik anda kasutajatele tagasisidet üles- või allalaadimistaotluse edenemise kohta. Selle hõlbustamiseks saate määrata oma onDownloadProgressi ja onUploadProgressi tagasihelistamised. Mõlemad tagasihelistamised aktsepteerivad sündmuse parameetrina AxiosProgressEvent. Taotluse edenedes kutsutakse neid tagasihelistusi mitu korda, mis võimaldab teil näiteks kuvada edenemisriba ja kohandada selle pikkust vastavalt edenemisele.
(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)
Liikmesuse ja krediitide kasutamine
Tagastab teie plaani sildi, kaasatud ja ettemakstud krediidijäägid ning kasutuse. Saate päringuid teha UTC kalendrikuu järgi (pärand), triipidega joondatud arveldusperioodi järgi (uuendamise kaudu jälgimiseks) või loetleda teadaolevad arveldusperioodid. Autentige ainult oma API võtmega.
Skeemide, näidete ja proovikonsooli vaatamiseks vaadake sama lõpp-punkti täielikus viites: Ava API dokumendid
Lõpp-punkt
GET https://www.rembg.com/api/membership-usageAutentimine
Saatke oma API võti: päis x-api-key: YOUR_API_KEY_HERE (looge ja hallake võtmeid oma profiilis saidil rembg.com).
Päringu parameetrid
| Parameeter | Sisestage | Kirjeldus |
|---|---|---|
| year | number | Kalendriaasta (1–9999). Kuu puhul on Redis võtmed kasutaja:{uid}:rakenduse_kasutus:{aasta}:{kuu}. Kui see on välja jäetud (ja periodStartUnixit ei kasutata), on vaikimisi kehtiv UTC aasta. |
| month | number (1–12) | Kalendri kuu 1–12 (klahvide puhul kasutatakse UTC tava). Kui see on välja jäetud, on vaikimisi kehtiv UTC kuu. |
| periodStartUnix | number | Unixi ajatempel sekundites: arveldusakna algus. Loeb kasutaja:{uid}:app_usage:cycle:{periodStartUnix} ja api_usage:cycle:…. Ei saa kombineerida aasta ega kuuga. |
| expand | string | Komaga eraldatud lipud. Kaasake arveldustsükkel, et lisada arveldustsükkel: praegune Stripe'i periood, kui arveldusperiood_* on Redises olemas, muul juhul praegune UTC kalendrikuu. Töötab konkreetse akna jaoks ka periodStartUnixiga. |
| includeBillingCycle | 1 / true | Sama, mis laiendamine, mis sisaldab billing_cycle: objekti billingCycle kaasamiseks määrake väärtusele 1 või tõene. |
| listBillingCycles | 1 / true | Spetsiaalne režiim: listBillingCycles=1 või tõene tagastab ainult { billingCycles: [...] }. Otsib Redis selle kasutaja tsükli võtmeid; teisi päringu parameetreid selle päringu puhul eiratakse. |
Ärge sisestage perioodiStartUnixit koos aasta või kuuga – API tagastab 400. Režiim listBillingCycles on eraldiseisev ja eirab muid parameetreid.
Loetlege arveldusperioodid
Kasutage seda varasemate ja praeguste tellimuste akende rippmenüü täitmiseks (iga kirje on periodStartUnix, mille saate tagasi saata koos periodStartUnix=…). Perioodi lõpu ajad on tuletatud (järgmise perioodi algus – 1 või Stripe praeguse_perioodi_lõpp aktiivse perioodi puhul).
curl --location 'https://www.rembg.com/api/membership-usage?listBillingCycles=1' \ --header 'x-api-key: YOUR_API_KEY_HERE'
Vastuse näidis
{
"billingCycles": [
{
"periodStartUnix": 1774268612,
"periodEndUnix": 1776947012,
"appUsage": 120,
"apiUsage": 880
}
]
}Kõigepealt sorteeritakse uusim periood. Punkt kuvatakse, kui on olemas tsükli kasutusvõti või kui see on Stripe'i veebihookide praegune arveldusperioodi_algamine.
Arveldustsükli objekt
Esitatakse, kui on määratud laiendamine hõlmab arveldustsüklit või includeBillingCycle. Kasutage seda armatuurlaudade jaoks: uuendamise piir, kasutamine aknas ja ülejäänud kaasatud krediidid.
| Väli | Kirjeldus |
|---|---|
| periodStartUnix | Arveldusakna algus (unix sekundit). Konto sünkroonimisel ühtib Stripe'i praeguse_perioodi_algamisega. |
| periodEndUnix | Praeguse akna lõpp (unixi sekundit), st vahetult enne järgmist uuendamist – sünkroonimisel triip praeguse_perioodi_lõpp. Ei ole sama mis tellimuse tühistamise kuupäev. |
| appUsage / apiUsage | Selles aknas arvestatud kaasatud krediidi kasutus: veebi/redaktor (rakendus) vs API võti (api). usedIncludedCredits võrdub nende summaga. |
| includedCredits | Teie kaasatud (plaani) krediidisumma, mis on salvestatud Redisesse (sama idee nagu tipptaseme krediitidel). |
| prepaidCredits | Ettemakstud (ostetud) saldo; ei lähtesta iga arveldusperioodi. |
| usedIncludedCredits | Aknas kaasatud kogukasutus (rakendus + API). Ettemakstud tarbimine siia ei lisandu. |
| remainingIncludedCredits | max(0, kaasatud krediitid − kasutatudKaasatud krediit) selle hetkepildi jaoks. |
| stripeBillingSynced | tõene, kui Redisel on Stripe'i arveldusperioodi algus/lõpp, nii et aken vastab teie tellimusele; false tähendab, et API langes selle ploki jaoks tagasi UTC kalendrikuule. |
Kuni Stripe'i veebihoogid pole kasutajale arveldusperioode kirjutanud, võib stripeBillingSynced olla vale ja arveldustsükli aken järgneb UTC kalendrikuule. Pärast sünkroonimist joonduvad pildi API kasutuspiirangud samade tsükliklahvidega.
Enne järgmist uuendamist kasutatud krediidi puhul helistage käsuga expand=billing_cycle ja kasutage uuendamise piirina billingCycle.periodEndUnix, billingCycle.usedIncludedCredits (või appUsage + apiUsage) ja billingCycle.remainingIncludedCredits. Lisage ettemakstud krediiti, kui soovite kogu kasutatavat saldot.
Näited (cURL)
Konkreetse UTC kalendrikuu kasutamine
curl --location 'https://www.rembg.com/api/membership-usage?year=2026&month=3' \ --header 'x-api-key: YOUR_API_KEY_HERE'
Praegune arveldustsükkel + täielik arveldustsükkel (sünkroonimisel uuendamine joondatud)
# 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'
Üks ajalooline arveldusaken perioodi alguse kaupa (nimekirjast BillingCycles või 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'
JSON-i näide (arveldustsükliga)
Tipptasemel app_usage ja api_usage kajastavad alati kas taotletud kalendrikuud või, kui periodStartUnix on määratud, siis selle tsükli loendureid. Kui expand=billing_cycle on välja jäetud, siis billingCycle puudub.
{
"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
}
}Kui stripeBillingSynced on tõene, vastab billingCycle taustal eemaldamise API jõustamisele. Kui see on vale, tuginege kalendrikuu väljadele või oodake, kuni veebihaagid täidavad Redises arveldusperioodi_*.
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