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 (застаріла версія), за розрахунковим періодом, вирівняним за смугою (для моніторингу через поновлення), або перераховувати відомі розрахункові періоди. Автентифікуйте лише за допомогою ключа 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.

Об’єкт billingCycle

Присутній, коли встановлено розширення, що включає 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 не записують розрахункові періоди для користувача, stripeBillingSynced може бути false, а вікно billingCycle слідувати за календарним місяцем за UTC. Після синхронізації обмеження на використання API зображень узгоджуються з тими самими ключами циклу.

Для «кредитів, використаних до наступного поновлення», викличте expand=billing_cycle і використовуйте billingCycle.periodEndUnix як межу поновлення, billingCycle.usedIncludedCredits (або appUsage + apiUsage) і billingCycle.remainingIncludedCredits. Додайте prepaidCredits, якщо вам потрібен загальний одноразовий баланс.

Приклади (cURL)

Використання за певний календарний місяць за UTC

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

Поточний платіжний цикл + повний блок billingCycle (оновлення вирівнюється під час синхронізації)

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

Одне історичне платіжне вікно за початком періоду (зі спискуBillingCycles або 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 видалення фону. Якщо значення false, покладайтеся на поля календарного місяця або чекайте, доки вебхуки заповнять 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