API Penghapusan Latar Belakang RemBG – Dokumen Pengembang & Panduan Integrasi






OpenAPI · Taman bermain langsung

Jelajahi API lengkap—jalankan permintaan nyata di browser Anda

Jelajahi setiap titik akhir, parameter, dan respons. Coba permintaan dengan kunci API Anda, lalu ambil spesifikasi mentah di /api/openapi kapan saja.

Luncurkan referensi interaktif

Pemasangan 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")
  • Menyiapkan Lingkungan Anda: Pastikan Anda memiliki file .env di root proyek yang berisi kunci API Anda.

  • Mengimpor Modul yang Diperlukan: Mulailah dengan mengimpor fungsi rembg dari @remove-background-ai/rembg.js dan modul dotenv untuk menangani variabel lingkungan.

  • Mengonfigurasi Callback Kemajuan: Pustaka menawarkan callback onDownloadProgress dan onUploadProgress untuk melacak kemajuan operasi file. Dalam contoh yang diberikan, kami mencatat peristiwa ini langsung ke konsol.

Sekarang, mari kita lihat lebih dekat contoh penggunaan:


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

Ingat, fungsi pembersihan dapat dipanggil jika Anda ingin menghapus gambar yang diproses dari disk Anda setelah penghapusan latar belakang.

Menampilkan bilah Kemajuan

Saat mengintegrasikan layanan penghapusan latar belakang, memberikan masukan kepada pengguna tentang kemajuan permintaan unggahan atau unduhan sering kali bermanfaat. Untuk memfasilitasi hal ini, Anda dapat menentukan callback onDownloadProgress dan onUploadProgress Anda sendiri. Kedua callback ini menerima AxiosProgressEvent sebagai parameter peristiwa. Saat permintaan berlanjut, callback ini dipanggil beberapa kali, sehingga memungkinkan Anda, misalnya, menampilkan bilah kemajuan dan menyesuaikan panjangnya berdasarkan kemajuan.


 (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
					

Keanggotaan & Penggunaan Kredit

Mengembalikan label paket Anda, saldo kredit yang disertakan dan prabayar, serta penggunaan. Anda dapat melakukan kueri berdasarkan bulan kalender UTC (lama), berdasarkan periode penagihan yang selaras dengan Stripe (untuk pemantauan melalui perpanjangan), atau mencantumkan periode penagihan yang diketahui. Autentikasi hanya dengan kunci API Anda.

Untuk skema, contoh, dan konsol uji coba, lihat titik akhir yang sama dalam referensi lengkap: Buka dokumen API

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

Kirim kunci API Anda: header x-api-key: YOUR_API_KEY_HERE (buat dan kelola kunci di profil Anda di rembg.com).

Parameter kueri
ParameterKetikDeskripsi
yearnumberTahun kalender (1–9999). Dengan bulan, baca kunci Redis pengguna:{uid}:app_usage:{tahun}:{bulan}. Jika dihilangkan (dan periodStartUnix tidak digunakan), defaultnya adalah tahun UTC saat ini.
monthnumber (1–12)Kalender bulan 1–12 (konvensi UTC digunakan untuk kunci). Jika dihilangkan, defaultnya adalah bulan UTC saat ini.
periodStartUnixnumberStempel waktu Unix dalam hitungan detik: dimulainya jendela penagihan. Membaca pengguna:{uid}:app_usage:cycle:{periodStartUnix} dan api_usage:cycle:…. Tidak dapat digabungkan dengan tahun atau bulan.
expandstringBendera yang dipisahkan koma. Sertakan billing_cycle untuk menambahkan objek billingCycle: periode Stripe saat ini ketika billing_period_* ada di Redis, jika tidak, bulan kalender UTC saat ini. Juga berfungsi dengan periodStartUnix untuk jendela tertentu.
includeBillingCycle1 / trueSama seperti perluasan yang berisi billing_cycle: disetel ke 1 atau true untuk menyertakan objek billingCycle.
listBillingCycles1 / trueMode khusus: listBillingCycles=1 atau true hanya mengembalikan { billingCycles: [...] }. Memindai Redis untuk mencari kunci siklus untuk pengguna ini; parameter kueri lainnya diabaikan pada permintaan ini.

Jangan meneruskan periodStartUnix bersamaan dengan tahun atau bulan — API mengembalikan 400. Mode listBillingCycles terpisah dan mengabaikan parameter lainnya.

Cantumkan periode penagihan

Gunakan ini untuk mengisi dropdown jendela langganan lama dan saat ini (setiap entri adalah periodStartUnix yang dapat Anda lewati kembali dengan periodStartUnix=…). Waktu akhir periode disimpulkan (awal periode berikutnya − 1, atau Stripe current_period_end untuk periode aktif).

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

Contoh tanggapan

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

Mengurutkan periode terbaru terlebih dahulu. Titik muncul jika ada kunci penggunaan siklus atau jika itu adalah billing_period_start saat ini dari webhook Stripe.

Objek Siklus Penagihan

Hadir ketika perluasan mencakup billing_cycle atau includeBillingCycle disetel. Gunakan untuk dasbor: batas pembaruan, penggunaan di jendela, dan sisa kredit yang disertakan.

BidangDeskripsi
periodStartUnixMulai jendela penagihan (unix detik). Cocok dengan Stripe current_period_start saat akun disinkronkan.
periodEndUnixAkhir jendela saat ini (unix detik), yaitu tepat sebelum pembaruan berikutnya — Stripe current_period_end saat disinkronkan. Tidak sama dengan tanggal pembatalan berlangganan.
appUsage / apiUsagePenggunaan kredit yang disertakan dihitung di jendela ini: web/editor (aplikasi) vs kunci API (api). UsedIncludedCredits sama dengan jumlahnya.
includedCreditsTunjangan kredit (paket) yang disertakan seperti yang disimpan di Redis (ide yang sama dengan kredit tingkat atas).
prepaidCreditsSaldo prabayar (dibeli); tidak mengatur ulang setiap periode penagihan.
usedIncludedCreditsTotal penggunaan yang disertakan di jendela (aplikasi + API). Konsumsi prabayar tidak ditambahkan di sini.
remainingIncludedCreditsmax(0, IncludedCredits − UsedIncludedCredits) untuk cuplikan ini.
stripeBillingSyncedbenar ketika Redis memiliki billing_period_start/end dari Stripe sehingga jendelanya cocok dengan langganan Anda; false berarti API kembali ke bulan kalender UTC untuk blok ini.

Hingga webhook Stripe menuliskan periode penagihan untuk pengguna, stripeBillingSynced mungkin salah dan jendela Siklus penagihan mengikuti bulan kalender UTC. Setelah sinkronisasi, batas penggunaan pada API gambar disejajarkan dengan kunci siklus yang sama.

Untuk “kredit yang digunakan sebelum perpanjangan berikutnya”, panggil dengan expand=billing_cycle dan gunakan billingCycle.periodEndUnix sebagai batas perpanjangan, billingCycle.usedIncludedCredits (atau appUsage + apiUsage), dan billingCycle.remainingIncludedCredits. Tambahkan Kredit prabayar jika Anda ingin total saldo yang dapat dibelanjakan.

Contoh (cURL)

Penggunaan untuk bulan kalender UTC tertentu

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

Siklus penagihan saat ini + blok siklus penagihan penuh (selaras dengan pembaruan saat disinkronkan)

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

Satu jendela penagihan historis berdasarkan periode awal (dari listBillingCycles atau 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'
Contoh JSON (dengan siklus penagihan)

App_usage dan api_usage tingkat atas selalu mencerminkan bulan kalender yang diminta atau, ketika periodStartUnix disetel, penghitung siklus tersebut. Jika expand=billing_cycle dihilangkan, billingCycle tidak ada.

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

Jika stripeBillingSynced benar, billingCycle mencocokkan penerapan pada API penghapusan latar belakang. Jika salah, andalkan kolom bulan kalender atau tunggu hingga webhook mengisi billing_period_* di 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