API za odstranjevanje ozadja RemBG – dokumenti za razvijalce in vodnik za integracijo

OpenAPI · Igrišče v živo

Raziščite celoten API – zaženite prave zahteve v brskalniku

Brskajte po vsaki končni točki, parametrih in odzivih. Preizkusite zahteve s svojim ključem API, nato pa kadar koli zgrabite neobdelano specifikacijo na /api/openapi.

Zaženi interaktivno referenco

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

Nastavitev vašega okolja: Zagotovite, da imate v korenu projekta datoteko .env, ki vsebuje vaš ključ API.
Uvoz potrebnih modulov: Začnite z uvozom funkcije rembg iz @remove-background-ai/rembg.js in modula dotenv za obdelavo spremenljivk okolja.
Konfiguriranje povratnih klicev napredka: Knjižnica ponuja povratne klice onDownloadProgress in onUploadProgress za spremljanje napredka operacij datotek. V navedenem primeru te dogodke beležimo neposredno v konzolo.

Zdaj pa si podrobneje oglejmo vzorec uporabe:


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

Ne pozabite, da lahko funkcijo čiščenja pokličete, če želite po odstranitvi ozadja z diska odstraniti obdelano sliko.

Prikaz vrstice napredka

Pri integraciji storitve odstranjevanja v ozadju je pogosto koristno, če uporabnikom zagotovite povratne informacije o napredku njihove zahteve za nalaganje ali prenos. Da bi to olajšali, lahko definirate svoja lastna povratna klica onDownloadProgress in onUploadProgress. Oba povratna klica sprejemata AxiosProgressEvent kot parameter dogodka. Ko se zahteva nadaljuje, se ti povratni klici večkrat prikličejo, kar vam omogoča, da na primer prikažete vrstico napredka in prilagodite njeno dolžino glede na napredek.


 (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)

Članstvo in uporaba dobropisov

Vrne oznako vašega načrta, vključena in predplačniška dobroimetja ter uporabo. Poizvedujete lahko po koledarskem mesecu UTC (podedovano), po obračunskem obdobju, usklajenem s Stripe (za spremljanje z obnovo) ali navedete znana obračunska obdobja. Preverjanje pristnosti samo s ključem API.

Za sheme, primere in preizkusno konzolo si oglejte isto končno točko v celotnem sklicu: Open API docs

Končna točka

GET https://www.rembg.com/api/membership-usage

Preverjanje pristnosti

Pošljite svoj API ključ: header x-api-key: YOUR_API_KEY_HERE (ustvari in upravljaj ključe v svojem profilu na rembg.com).

Parametri poizvedbe

Parameter	Vrsta	Opis
year	number	Koledarsko leto (1–9999). Z mesecem bere uporabnik ključev Redis:{uid}:app_usage:{year}:{month}. Če je izpuščen (in periodStartUnix ni uporabljen), je privzeto nastavljeno na trenutno leto UTC.
month	number (1–12)	Koledarski mesec 1–12 (za ključe se uporablja konvencija UTC). Če je izpuščeno, je privzet trenutni mesec UTC.
periodStartUnix	number	Časovni žig Unix v sekundah: začetek obračunskega okna. Bere user:{uid}:app_usage:cycle:{periodStartUnix} in api_usage:cycle:…. Ni mogoče kombinirati z letom ali mesecem.
expand	string	Zastavice, ločene z vejicami. Vključite billing_cycle, da dodate predmet billingCycle: trenutno obdobje Stripe, ko billing_period_* obstaja v Redisu, sicer trenutni koledarski mesec UTC. Deluje tudi s periodStartUnix za določeno okno.
includeBillingCycle	1 / true	Enako kot razširitev, ki vsebuje billing_cycle: nastavite na 1 ali true, da vključite predmet billingCycle.
listBillingCycles	1 / true	Namenski način: listBillingCycles=1 ali true vrne samo { billingCycles: [...] }. Pregleda Redis za ciklične ključe za tega uporabnika; drugi parametri poizvedbe so pri tej zahtevi prezrti.

Ne posredujte periodStartUnix skupaj z letom ali mesecem — API vrne 400. Način listBillingCycles je ločen in ignorira druge parametre.

Seznam obračunskih obdobij

Uporabite to za zapolnitev spustnega menija preteklih in trenutnih naročniških oken (vsak vnos je periodStartUnix, ki ga lahko vrnete s periodStartUnix=…). Ugotovljeni so končni časi obdobja (začetek naslednjega obdobja − 1 ali Stripe current_period_end za aktivno obdobje).

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

Primer odgovora

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

Najprej razvrščeno najnovejše obdobje. Obdobje se prikaže, če obstaja ključ uporabe cikla ali če je trenutni billing_period_start iz webhookov Stripe.

Objekt billingCycle

Prisoten, ko je nastavljena razširitev vključuje billing_cycle ali includeBillingCycle. Uporabite ga za nadzorne plošče: meja podaljšanja, uporaba v oknu in preostali vključeni krediti.

Polje	Opis
periodStartUnix	Začetek obračunskega okna (unix sekunde). Ujema se s Stripe current_period_start, ko je račun sinhroniziran.
periodEndUnix	Konec trenutnega okna (unix sekunde), tj. tik pred naslednjo obnovitvijo — Stripe current_period_end ob sinhronizaciji. Ni isto kot datum preklica naročnine.
appUsage / apiUsage	Uporaba vključenega kredita, šteta v tem oknu: splet/urejevalnik (aplikacija) v primerjavi s ključem API (api). usedIncludedCredits je enak njihovi vsoti.
includedCredits	Vaše vključeno (načrtovano) dobroimetje, kot je shranjeno v Redis (enaka ideja kot krediti na najvišji ravni).
prepaidCredits	Predplačniško (kupljeno) stanje; ne ponastavi vsakega obračunskega obdobja.
usedIncludedCredits	Skupna vključena uporaba v oknu (aplikacija + API). Predplačniška poraba se tukaj ne prišteva.
remainingIncludedCredits	max(0, includedCredits − usedIncludedCredits) za ta posnetek.
stripeBillingSynced	true, ko ima Redis billing_period_start/end od Stripe, tako da se okno ujema z vašo naročnino; false pomeni, da se je API za ta blok vrnil na koledarski mesec UTC.

Dokler webhooks Stripe ne zapišejo obračunskih obdobij za uporabnika, je lahko stripeBillingSynced napačen in okno billingCycle sledi koledarskemu mesecu UTC. Po sinhronizaciji se omejitve uporabe slikovnega API-ja uskladijo z istimi cikličnimi ključi.

Za »kredite, uporabljene pred naslednjo obnovitvijo«, pokličite z expand=billing_cycle in uporabite billingCycle.periodEndUnix kot mejo obnovitve, billingCycle.usedIncludedCredits (ali appUsage + apiUsage) in billingCycle.remainingIncludedCredits. Dodajte predplačniške kredite, če želite skupno razpoložljivo stanje.

Primeri (cURL)

Poraba za določen koledarski mesec UTC

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

Trenutni obračunski cikel + celoten blok obračunskega cikla (obnovitev poravnana ob sinhronizaciji)

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

Eno zgodovinsko obračunsko obdobje po začetku obdobja (s seznama BillingCycles ali 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'

Primer JSON (z obračunskim ciklom)

App_usage in api_usage na najvišji ravni vedno odražata zahtevani koledarski mesec ali, ko je periodStartUnix nastavljen, števce tega cikla. Če je expand=billing_cycle izpuščen, je billingCycle odsoten.

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

Če je stripeBillingSynced nastavljen na true, se billingCycle ujema z uveljavljanjem v API-ju za odstranjevanje ozadja. Če je nastavljeno na false, se zanašajte na polja koledarskega meseca ali počakajte, da webhooki izpolnijo billing_period_* v Redisu.

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
}

Multiple Validation Errors Response