RemBG Background Removal API – kūrėjo dokumentai ir integravimo vadovas






OpenAPI · Tiesioginė žaidimų aikštelė

Naršykite visą API – vykdykite tikras užklausas savo naršyklėje

Naršykite kiekvieną galutinį tašką, parametrus ir atsakymus. Išbandykite užklausas naudodami API raktą, tada bet kada gaukite neapdorotą specifikaciją adresu /api/openapi.

Paleisti interaktyvią nuorodą

Rembg.js diegimas

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")
  • Aplinkos nustatymas: Įsitikinkite, kad projekto šaknyje turite .env failą su API raktu.

  • Būtinų modulių importavimas: Pradėkite importuodami funkciją rembg iš @remove-background-ai/rembg.js ir dotenv modulį, kad galėtumėte tvarkyti aplinkos kintamuosius.

  • Pažangos atgalinių skambučių konfigūravimas: Biblioteka siūlo onDownloadProgress ir onUploadProgress atgalinius skambučius, kad būtų galima stebėti failo operacijų eigą. Pateiktame pavyzdyje šiuos įvykius registruojame tiesiai į konsolę.

Dabar atidžiau pažvelkime į naudojimo pavyzdį:


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

Atminkite, kad valymo funkcija gali būti iškviesta, jei norite pašalinti apdorotą vaizdą iš disko pašalinus foną.

Rodoma eigos juosta

Integruojant fono pašalinimo paslaugą, dažnai naudinga pateikti naudotojams atsiliepimų apie jų įkėlimo arba atsisiuntimo užklausos eigą. Norėdami tai palengvinti, galite nustatyti savo onDownloadProgress ir onUploadProgress atgalinius skambučius. Abu šie atgaliniai skambučiai priima AxiosProgressEvent kaip įvykio parametrą. Vykdant užklausą, šie atgaliniai skambučiai iškviečiami kelis kartus, todėl galite, pavyzdžiui, rodyti eigos juostą ir koreguoti jos ilgį pagal eigą.


 (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
					

Narystė ir kreditų naudojimas

Grąžina plano etiketę, įtrauktus ir iš anksto apmokėtus kredito likučius bei naudojimą. Galite pateikti užklausą pagal UTC kalendorinį mėnesį (seną), pagal juosteles suderintą atsiskaitymo laikotarpį (stebėti atnaujinant) arba išvardyti žinomus atsiskaitymo laikotarpius. Autentifikuokite tik naudodami API raktą.

Jei reikia schemų, pavyzdžių ir bandomosios konsolės, žr. tą patį galutinį tašką visoje nuorodoje: Atidaryti API dokumentus

Galutinis taškas
GET https://www.rembg.com/api/membership-usage
Autentifikavimas

Išsiųskite savo API raktą: antraštė x-api-key: YOUR_API_KEY_HERE (kurkite ir tvarkykite raktus savo profilyje rembg.com).

Užklausos parametrai
ParametrasĮveskiteAprašymas
yearnumberKalendoriniai metai (1–9999). Su mėnesiu rašoma Redis Keys user:{uid}:app_usage:{year}:{month}. Jei praleista (ir periodStartUnix nenaudojamas), pagal numatytuosius nustatymus bus nustatyti dabartiniai UTC metai.
monthnumber (1–12)1–12 kalendorinis mėnuo (raktiems naudojama UTC konvencija). Jei praleista, numatytasis dabartinis UTC mėnuo.
periodStartUnixnumberUnix laiko žyma sekundėmis: atsiskaitymo lango pradžia. Skaito user:{uid}:app_usage:cycle:{periodStartUnix} ir api_usage:cycle:…. Negalima derinti su metais ar mėnesiu.
expandstringKableliais atskirtos vėliavėlės. Įtraukite billing_cycle, kad pridėtumėte objektą billingCycle: dabartinis Stripe laikotarpis, kai "Redis" yra billing_period_*, kitu atveju dabartinis UTC kalendorinis mėnuo. Taip pat veikia su periodStartUnix konkrečiam langui.
includeBillingCycle1 / trueTas pats, kaip išplėtimas su billing_cycle: nustatykite 1 arba true, kad įtrauktumėte objektą billingCycle.
listBillingCycles1 / trueSkirtas režimas: listBillingCycles=1 arba tikra grąžina tik { billingCycles: [...] }. Nuskaito Redis šio vartotojo ciklo klavišus; kiti užklausos parametrai šioje užklausoje nepaisomi.

Neperduokite periodStartUnix kartu su metais ar mėnesiu – API grąžina 400. ListBillingCycles režimas yra atskiras ir nepaiso kitų parametrų.

Atsiskaitymo laikotarpių sąrašas

Naudokite tai norėdami užpildyti ankstesnių ir dabartinių prenumeratos langų išskleidžiamąjį meniu (kiekvienas įrašas yra periodStartUnix, kurį galite grąžinti naudodami periodStartUnix=…). Nurodomas laikotarpio pabaigos laikas (kito laikotarpio pradžia – 1 arba aktyvaus laikotarpio Stripe current_period_end).

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

Atsakymo pavyzdys

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

Pirmiausia rūšiuojamas naujausias laikotarpis. Taškas rodomas, jei yra ciklo naudojimo raktas arba jei tai yra dabartinis billing_period_start iš Stripe webhooks.

BillingCycle objektas

Pateikiama, kai nustatytas išplėtimas apima sąskaitų_ciklą arba įtrauktiBillingCycle. Naudokite jį prietaisų skydeliams: atnaujinimo ribai, naudojimui lange ir likusiems įtrauktiems kreditams.

LaukasAprašymas
periodStartUnixAtsiskaitymo lango pradžia (unix sekundės). Atitinka Stripe current_period_start, kai paskyra sinchronizuojama.
periodEndUnixDabartinio lango pabaiga (unix sekundės), t. y. prieš pat kitą atnaujinimą – sinchronizuojama juostelė current_period_end. Ne tas pats, kas prenumeratos atšaukimo data.
appUsage / apiUsageĮtraukto kredito naudojimas, skaičiuojamas šiame lange: žiniatinklio / redaktoriaus (programa) ir API rakto (api). UsedIncludedCredits yra lygus jų sumai.
includedCreditsJūsų įtraukta (plano) kredito išmoka, saugoma Redis (ta pati idėja kaip aukščiausio lygio kreditai).
prepaidCreditsIš anksto apmokėtas (pirktas) likutis; nenustato kiekvieno atsiskaitymo laikotarpio iš naujo.
usedIncludedCreditsVisas įtrauktas naudojimas lange (programa + API). Iš anksto apmokėtas suvartojimas čia nepridėtas.
remainingIncludedCreditsmax(0, įtrauktaKreditai − naudojamiĮtraukti kreditai) šiai momentinei nuotraukai.
stripeBillingSyncedtiesa, kai Redis turi atsiskaitymo_periodo_pradžia/pabaiga iš Stripe, todėl langas atitinka jūsų prenumeratą; false reiškia, kad šio bloko API nukrito iki UTC kalendorinio mėnesio.

Kol „Stripe Webhooks“ neparašė naudotojo atsiskaitymo laikotarpių, „stripeBillingSynced“ gali būti klaidinga, o atsiskaitymo ciklo langas eina po UTC kalendorinio mėnesio. Po sinchronizavimo vaizdo API naudojimo apribojimai sutampa su tais pačiais ciklo klavišais.

Jei norite sužinoti apie kreditus, panaudotus prieš kitą atnaujinimą, skambinkite naudodami expand=billing_cycle ir kaip atnaujinimo ribą naudokite billingCycle.periodEndUnix, billingCycle.usedIncludedCredits (arba appUsage + apiUsage) ir billingCycle.remainingIncludedCredits. Pridėkite išankstinio mokėjimo kreditus, jei norite viso disponuojamo likučio.

Pavyzdžiai (cURL)

Naudojimas konkrečiam UTC kalendoriniam mėnesiui

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

Dabartinis atsiskaitymo ciklas + visas atsiskaitymo Ciklo blokas (atnaujinimas suderinamas, kai sinchronizuojamas)

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

Vienas istorinis atsiskaitymo langas pagal laikotarpio pradžią (iš listBillingCycles arba 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 pavyzdys (su atsiskaitymo ciklu)

Aukščiausio lygio app_usage ir api_usage visada atspindi prašomą kalendorinį mėnesį arba, kai nustatyta periodStartUnix, to ciklo skaitiklius. Kai praleidžiamas expand=billing_cycle, billingCycle nėra.

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

Kai „StripeBillingSynced“ yra tiesa, „billingCycle“ atitinka fono pašalinimo API vykdymą. Kai klaidinga, pasikliaukite kalendorinio mėnesio laukais arba palaukite, kol „Webhooks“ užpildys „Redis“ atsiskaitymo_periodį_*.

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