RemBG Background Removal API – Документи за разработчици и ръководство за интегриране






OpenAPI · Игра на живо

Разгледайте пълния API – изпълнявайте реални заявки във вашия браузър

Прегледайте всяка крайна точка, параметри и отговори. Опитайте заявки с вашия API ключ, след което вземете необработената спецификация в /api/openapi по всяко време.

Стартиране на интерактивна справка

Инсталиране на rembg.js

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")
  • Настройване на вашата среда: Уверете се, че имате .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
					

Членство и използване на кредити

Връща етикета на вашия план, включени и предплатени кредитни салда и използване. Можете да правите заявки по UTC календарен месец (наследено), по период на фактуриране, подравнен по Stripe (за наблюдение чрез подновяване), или да изброявате известни периоди на фактуриране. Удостоверете само с вашия API ключ.

За схеми, примери и конзола за изпробване вижте същата крайна точка в пълната справка: Open API документи

Крайна точка
GET https://www.rembg.com/api/membership-usage
Удостоверяване

Изпратете своя API ключ: header x-api-key: YOUR_API_KEY_HERE (създайте и управлявайте ключове във вашия профил в rembg.com).

Параметри на заявката
ПараметърТипОписание
yearnumberКалендарна година (1–9999). С месец, чете Redis ключове user:{uid}:app_usage:{year}:{month}. Ако е пропуснато (и periodStartUnix не се използва), по подразбиране е текущата UTC година.
monthnumber (1–12)Календарен месец 1–12 (UTC конвенция, използвана за ключове). Ако е пропуснато, по подразбиране е текущият месец UTC.
periodStartUnixnumberВремево клеймо на Unix в секунди: начало на прозорец за фактуриране. Чете user:{uid}:app_usage:cycle:{periodStartUnix} и api_usage:cycle:…. Не може да се комбинира с година или месец.
expandstringФлагове, разделени със запетая. Включете billing_cycle, за да добавите обект billingCycle: текущ период на Stripe, когато billing_period_* съществува в Redis, в противен случай текущият UTC календарен месец. Също така работи с periodStartUnix за конкретен прозорец.
includeBillingCycle1 / trueСъщото като разгъване, съдържащо billing_cycle: задайте на 1 или true, за да включите обекта billingCycle.
listBillingCycles1 / 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_period_start от Stripe webhooks.

Обектът billingCycle

Присъства, когато е зададено expand include billing_cycle или includeBillingCycle. Използвайте го за табла за управление: граница на подновяване, използване в прозореца и оставащи включени кредити.

ПолеОписание
periodStartUnixНачало на прозореца за фактуриране (unix секунди). Съответства на Stripe current_period_start, когато акаунтът е синхронизиран.
periodEndUnixКрай на текущия прозорец (unix секунди), т.е. точно преди следващото подновяване — Stripe current_period_end при синхронизиране. Не е същото като датата на анулиране на абонамента.
appUsage / apiUsageИзползването на включен кредит, отчетено в този прозорец: уеб/редактор (приложение) срещу API ключ (api). usedIncludedCredits е равно на тяхната сума.
includedCreditsВашата включена (планова) кредитна надбавка, както се съхранява в Redis (същата идея като кредитите от най-високо ниво).
prepaidCreditsПредплатен (закупен) баланс; не нулира всеки период на фактуриране.
usedIncludedCreditsОбщо включено използване в прозореца (приложение + API). Тук не се добавя предплатена консумация.
remainingIncludedCreditsmax(0, includedCredits − usedIncludedCredits) за тази моментна снимка.
stripeBillingSyncedtrue, когато Redis има billing_period_start/end от Stripe, така че прозорецът съответства на вашия абонамент; false означава, че API е върнат до UTC календарен месец за този блок.

Докато Stripe webhooks не са записали периоди на фактуриране за потребителя, stripeBillingSynced може да е невярно и прозорецът billingCycle следва календарния месец UTC. След синхронизиране ограниченията за използване на API за изображения се подравняват със същите циклични ключове.

За „кредити, използвани преди следващото подновяване“, извикайте с expand=billing_cycle и използвайте billingCycle.periodEndUnix като граница на подновяване, billingCycle.usedIncludedCredits (или appUsage + apiUsage) и billingCycle.remainingIncludedCredits. Добавете предплатени кредити, ако искате общо разполагаемо салдо.

Примери (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 е true, billingCycle съответства на прилагането на API за премахване на заден план. Когато е невярно, разчитайте на полетата за календарен месец или изчакайте, докато уеб кукичките попълнят 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
}

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