RemBG Background Removal API – Developer Docs & Integration Guide

OpenAPI · Ζωντανή παιδική χαρά

Εξερευνήστε το πλήρες API—εκτελέστε πραγματικά αιτήματα στο πρόγραμμα περιήγησής σας

Περιηγηθείτε σε κάθε τελικό σημείο, παραμέτρους και απαντήσεις. Δοκιμάστε αιτήματα με το κλειδί API σας και, στη συνέχεια, πάρτε την ακατέργαστη προδιαγραφή στο /api/openapi ανά πάσα στιγμή.

Εκκίνηση διαδραστικής αναφοράς

Εγκατάσταση του 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")

Ρύθμιση του περιβάλλοντος σας: Βεβαιωθείτε ότι έχετε ένα αρχείο .env στη ρίζα του έργου σας που περιέχει το κλειδί API σας.
Εισαγωγή των απαραίτητων ενοτήτων: Ξεκινήστε εισάγοντας τη συνάρτηση rembg από το @remove-background-ai/rembg.js και τη λειτουργική μονάδα dotenv για να χειριστείτε μεταβλητές περιβάλλοντος.
Διαμόρφωση επανάκλησης προόδου: Η βιβλιοθήκη προσφέρει επιστροφές κλήσης onDownloadProgress και onUploadProgress για την παρακολούθηση της προόδου των λειτουργιών αρχείων. Στο παρεχόμενο παράδειγμα, καταγράφουμε αυτά τα συμβάντα απευθείας στην κονσόλα.

Τώρα, ας ρίξουμε μια πιο προσεκτική ματιά σε ένα δείγμα χρήσης:


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

Να θυμάστε ότι η λειτουργία εκκαθάρισης μπορεί να κληθεί εάν θέλετε να αφαιρέσετε την επεξεργασμένη εικόνα από τον δίσκο σας μετά την αφαίρεση του φόντου.

Εμφάνιση γραμμής προόδου

Όταν ενσωματώνετε μια υπηρεσία αφαίρεσης παρασκηνίου, είναι συχνά ωφέλιμο να παρέχετε στους χρήστες σχόλια σχετικά με την πρόοδο του αιτήματος μεταφόρτωσης ή λήψης. Για να διευκολυνθεί αυτό, μπορείτε να ορίσετε τις δικές σας επιστροφές κλήσης onDownloadProgress και onUploadProgress. Και οι δύο αυτές επανακλήσεις δέχονται το AxiosProgressEvent ως παράμετρο συμβάντος. Καθώς το αίτημα προχωρά, αυτές οι επανακλήσεις καλούνται πολλές φορές, επιτρέποντάς σας, για παράδειγμα, να εμφανίσετε μια γραμμή προόδου και να προσαρμόσετε το μήκος της με βάση την πρόοδο.


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

Συνδρομή και χρήση πιστώσεων

Επιστρέφει την ετικέτα του προγράμματος, τα περιλαμβανόμενα και προπληρωμένα πιστωτικά υπόλοιπα και τη χρήση. Μπορείτε να υποβάλετε ερωτήματα ανά ημερολογιακό μήνα UTC (παλαιού τύπου), ανά περίοδο χρέωσης ευθυγραμμισμένη με λωρίδες (για παρακολούθηση μέσω ανανέωσης) ή λίστα γνωστών περιόδων χρέωσης. Πραγματοποιήστε έλεγχο ταυτότητας μόνο με το κλειδί API σας.

Για σχήματα, παραδείγματα και μια κονσόλα try-it, δείτε το ίδιο τελικό σημείο στην πλήρη αναφορά: Άνοιγμα εγγράφων API

Τελικό σημείο

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

Έλεγχος ταυτότητας

Στείλτε το κλειδί API σας: κεφαλίδα x-api-key: YOUR_API_KEY_HERE (δημιουργήστε και διαχειριστείτε κλειδιά στο προφίλ σας στο rembg.com).

Παράμετροι ερωτήματος

Παράμετρος	Τύπος	Περιγραφή
year	number	Ημερολογιακό έτος (1–9999). Με μήνα, διαβάζεται Redis keys user:{uid}:app_usage:{year}:{month}. Εάν παραλειφθεί (και το periodStartUnix δεν χρησιμοποιείται), ορίζεται από προεπιλογή το τρέχον έτος UTC.
month	number (1–12)	Ημερολογιακός μήνας 1–12 (η σύμβαση UTC χρησιμοποιείται για τα κλειδιά). Εάν παραλειφθεί, ορίζεται από προεπιλογή ο τρέχων μήνας UTC.
periodStartUnix	number	Χρονική σήμανση Unix σε δευτερόλεπτα: έναρξη ενός παραθύρου χρέωσης. Διαβάζει χρήστη:{uid}:app_usage:cycle:{periodStartUnix} και api_usage:cycle:…. Δεν μπορεί να συνδυαστεί με έτος ή μήνα.
expand	string	Σημαίες διαχωρισμένες με κόμματα. Συμπεριλάβετε το billing_cycle για να προσθέσετε ένα αντικείμενο billingCycle: τρέχουσα περίοδος Stripe όταν υπάρχει billing_period_* στο Redis, διαφορετικά ο τρέχων ημερολογιακός μήνας UTC. Λειτουργεί επίσης με το periodStartUnix για ένα συγκεκριμένο παράθυρο.
includeBillingCycle	1 / true	Ίδιο με την επέκταση που περιέχει billing_cycle: ορίστε σε 1 ή true για να συμπεριλάβετε το αντικείμενο billingCycle.
listBillingCycles	1 / true	Αποκλειστική λειτουργία: listBillingCycles=1 ή true επιστρέφει μόνο { billingCycles: [...] }. Σαρώνει το Redis για κλειδιά κύκλου για αυτόν τον χρήστη. άλλες παράμετροι ερωτήματος αγνοούνται σε αυτό το αίτημα.

Μην περάσετε το periodStartUnix μαζί με το έτος ή τον μήνα — το API επιστρέφει 400. Η λειτουργία listBillingCycles είναι ξεχωριστή και αγνοεί άλλες παραμέτρους.

Λίστα περιόδων χρέωσης

Χρησιμοποιήστε το για να συμπληρώσετε ένα αναπτυσσόμενο μενού με τα προηγούμενα και τα τρέχοντα παράθυρα συνδρομής (κάθε καταχώρηση είναι ένα periodStartUnix που μπορείτε να επιστρέψετε με periodStartUnix=…). Συνάγονται οι χρόνοι λήξης της περιόδου (έναρξη επόμενης περιόδου − 1 ή Stripe current_period_end για την ενεργή περίοδο).

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

Παράδειγμα απάντησης

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

Ταξινόμησε πρώτα την νεότερη περίοδο. Μια τελεία εμφανίζεται εάν υπάρχει κλειδί χρήσης κύκλου ή εάν είναι η τρέχουσα περίοδος_έναρξης_billing από τα Stripe webhook.

Το αντικείμενο billingCycle

Παρουσιάζεται όταν έχει οριστεί η επέκταση περιλαμβάνει billing_cycle ή περιλαμβάνει τον κύκλο χρέωσης. Χρησιμοποιήστε το για πίνακες εργαλείων: όριο ανανέωσης, χρήση στο παράθυρο και υπολειπόμενες μονάδες που περιλαμβάνονται.

Πεδίο	Περιγραφή
periodStartUnix	Έναρξη του παραθύρου χρέωσης (unix δευτερόλεπτα). Ταιριάζει με το Stripe current_period_start όταν ο λογαριασμός συγχρονίζεται.
periodEndUnix	Τέλος του τρέχοντος παραθύρου (unix δευτερόλεπτα), δηλαδή λίγο πριν από την επόμενη ανανέωση — λωρίδα current_period_end κατά τον συγχρονισμό. Δεν είναι ίδια με την ημερομηνία ακύρωσης συνδρομής.
appUsage / apiUsage	Η χρήση συμπεριλαμβανομένης πίστωσης υπολογίζεται σε αυτό το παράθυρο: web/editor (εφαρμογή) έναντι κλειδιού API (api). usedIncludedCredits ισούται με το άθροισμά τους.
includedCredits	Το περιλαμβανόμενο επίδομα πίστωσης (πρόγραμμα) όπως είναι αποθηκευμένο στο Redis (ίδια ιδέα με τις πιστώσεις ανώτατου επιπέδου).
prepaidCredits	Προπληρωμένο (αγορασμένο) υπόλοιπο. δεν επαναφέρει κάθε περίοδο χρέωσης.
usedIncludedCredits	Συνολική περιλαμβανόμενη χρήση στο παράθυρο (εφαρμογή + API). Η προπληρωμένη κατανάλωση δεν προστίθεται εδώ.
remainingIncludedCredits	max(0, περιλαμβάνονταιΠιστώσεις − usedIncludedCredits) για αυτό το στιγμιότυπο.
stripeBillingSynced	true όταν το Redis έχει billing_period_start/end από το Stripe, ώστε το παράθυρο να ταιριάζει με τη συνδρομή σας. false σημαίνει ότι το API μειώθηκε σε ημερολογιακό μήνα UTC για αυτό το μπλοκ.

Έως ότου τα Stripe webhook έχουν γράψει περιόδους χρέωσης για τον χρήστη, το stripeBillingSynced μπορεί να είναι ψευδές και το παράθυρο billingCycle ακολουθεί τον ημερολογιακό μήνα UTC. Μετά τον συγχρονισμό, τα όρια χρήσης στο API εικόνας ευθυγραμμίζονται με τα ίδια πλήκτρα κύκλου.

Για "πιστώσεις που χρησιμοποιούνται πριν από την επόμενη ανανέωση", καλέστε με expand=billing_cycle και χρησιμοποιήστε το billingCycle.periodEndUnix ως όριο ανανέωσης, το billingCycle.usedIncludedCredits (ή appUsage + apiUsage) και το billingCycle.remainingIncludedCredit. Προσθέστε προπληρωμένες πιστώσεις εάν θέλετε το συνολικό υπόλοιπο μιας χρήσης.

Παραδείγματα (cURL)

Χρήση για συγκεκριμένο ημερολογιακό μήνα UTC

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

Τρέχων κύκλος χρέωσης + πλήρες μπλοκ κύκλου χρέωσης (ευθυγράμμιση ανανέωσης όταν συγχρονίζεται)

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

Ένα ιστορικό παράθυρο χρέωσης ανά περίοδο έναρξης (από listBillingCycles ή 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 (με κύκλο χρέωσης)

Το app_usage και το api_usage ανώτατου επιπέδου αντικατοπτρίζουν πάντα είτε τον ζητούμενο ημερολογιακό μήνα είτε, όταν έχει οριστεί η periodStartUnix, οι μετρητές αυτού του κύκλου. Όταν το expand=billing_cycle παραλείπεται, το billingCycle απουσιάζει.

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

Όταν το stripeBillingSynced είναι αληθές, το billingCycle ταιριάζει με την επιβολή στο API αφαίρεσης φόντου. Όταν είναι false, βασιστείτε σε πεδία ημερολογιακού μήνα ή περιμένετε μέχρι τα webhook να συμπληρώσουν billing_period_* στο Redis.

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