RemBG tausta eemaldamise API – arendaja dokumendid ja integreerimisjuhend






OpenAPI · Reaalajas mänguväljak

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 viide

Faili rembg.js installimine

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")
  • 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
					

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-usage
Autentimine

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
ParameeterSisestageKirjeldus
yearnumberKalendriaasta (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.
monthnumber (1–12)Kalendri kuu 1–12 (klahvide puhul kasutatakse UTC tava). Kui see on välja jäetud, on vaikimisi kehtiv UTC kuu.
periodStartUnixnumberUnixi ajatempel sekundites: arveldusakna algus. Loeb kasutaja:{uid}:app_usage:cycle:{periodStartUnix} ja api_usage:cycle:…. Ei saa kombineerida aasta ega kuuga.
expandstringKomaga 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.
includeBillingCycle1 / trueSama, mis laiendamine, mis sisaldab billing_cycle: objekti billingCycle kaasamiseks määrake väärtusele 1 või tõene.
listBillingCycles1 / trueSpetsiaalne 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äliKirjeldus
periodStartUnixArveldusakna algus (unix sekundit). Konto sünkroonimisel ühtib Stripe'i praeguse_perioodi_algamisega.
periodEndUnixPraeguse 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 / apiUsageSelles aknas arvestatud kaasatud krediidi kasutus: veebi/redaktor (rakendus) vs API võti (api). usedIncludedCredits võrdub nende summaga.
includedCreditsTeie kaasatud (plaani) krediidisumma, mis on salvestatud Redisesse (sama idee nagu tipptaseme krediitidel).
prepaidCreditsEttemakstud (ostetud) saldo; ei lähtesta iga arveldusperioodi.
usedIncludedCreditsAknas kaasatud kogukasutus (rakendus + API). Ettemakstud tarbimine siia ei lisandu.
remainingIncludedCreditsmax(0, kaasatud krediitid − kasutatudKaasatud krediit) selle hetkepildi jaoks.
stripeBillingSyncedtõ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.

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