API Pembuangan Latar Belakang RemBG – Dokumen Pembangun & Panduan Penyepaduan






OpenAPI · Taman permainan langsung

Terokai API penuh—jalankan permintaan sebenar dalam penyemak imbas anda

Semak imbas setiap titik akhir, parameter dan respons. Cuba permintaan dengan kunci API anda, kemudian ambil spesifikasi mentah di /api/openapi pada bila-bila masa.

Lancarkan rujukan 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")
  • Menyediakan Persekitaran Anda: Pastikan anda mempunyai fail .env dalam akar projek anda yang mengandungi kunci API anda.

  • Mengimport Modul yang Diperlukan: Mulakan dengan mengimport fungsi rembg daripada @remove-background-ai/rembg.js dan modul dotenv untuk mengendalikan pembolehubah persekitaran.

  • Mengkonfigurasi Panggilan Balik Kemajuan: Pustaka menawarkan panggilan balik onDownloadProgress dan onUploadProgress untuk menjejaki kemajuan operasi fail. Dalam contoh yang diberikan, kami mengelog acara ini terus ke konsol.

Sekarang, mari kita lihat lebih dekat pada 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 boleh dipanggil jika anda ingin mengalih keluar imej yang diproses daripada cakera anda selepas dialih keluar latar belakang.

Menunjukkan bar Kemajuan

Apabila menyepadukan perkhidmatan alih keluar latar belakang, selalunya berfaedah untuk memberi pengguna maklum balas tentang kemajuan permintaan muat naik atau muat turun mereka. Untuk memudahkan ini, anda boleh menentukan panggilan balik onDownloadProgress dan onUploadProgress anda sendiri. Kedua-dua panggilan balik ini menerima AxiosProgressEvent sebagai parameter acara. Semasa permintaan diteruskan, panggilan balik ini digunakan beberapa kali, membolehkan anda, contohnya, memaparkan bar kemajuan dan melaraskan 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
					

Penggunaan Keahlian & Kredit

Mengembalikan label pelan anda, termasuk dan baki kredit prabayar serta penggunaan. Anda boleh membuat pertanyaan mengikut bulan kalendar UTC (warisan), mengikut tempoh pengebilan sejajar Stripe (untuk pemantauan melalui pembaharuan), atau menyenaraikan tempoh pengebilan yang diketahui. Sahkan dengan kunci API anda sahaja.

Untuk skema, contoh dan konsol cuba, lihat titik akhir yang sama dalam rujukan penuh: Buka dokumen API

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

Hantar kunci API anda: header x-api-key: YOUR_API_KEY_HERE (buat dan urus kunci dalam profil anda di rembg.com).

Parameter pertanyaan
ParameterTaipkanPenerangan
yearnumberTahun kalendar (1–9999). Dengan bulan, membaca kunci Redis pengguna:{uid}:app_usage:{year}:{month}. Jika ditinggalkan (dan periodStartUnix tidak digunakan), lalai kepada tahun UTC semasa.
monthnumber (1–12)Kalendar bulan 1–12 (konvensyen UTC digunakan untuk kunci). Jika ditinggalkan, lalai kepada bulan UTC semasa.
periodStartUnixnumberCap waktu Unix dalam beberapa saat: permulaan tetingkap pengebilan. Membaca pengguna:{uid}:app_usage:cycle:{periodStartUnix} dan api_usage:cycle:…. Tidak boleh digabungkan dengan tahun atau bulan.
expandstringBendera dipisahkan koma. Sertakan billing_cycle untuk menambah objek BillingCycle: tempoh Jalur semasa apabila billing_period_* wujud dalam Redis, jika tidak, bulan kalendar UTC semasa. Juga berfungsi dengan periodStartUnix untuk tetingkap tertentu.
includeBillingCycle1 / trueSama seperti kembangkan yang mengandungi kitaran_bilan: ditetapkan kepada 1 atau benar untuk memasukkan objek Kitaran pengebilan.
listBillingCycles1 / trueMod khusus: listBillingCycles=1 atau pulangan benar sahaja { billingCycles: [...] }. Mengimbas Redis untuk kunci kitaran untuk pengguna ini; parameter pertanyaan lain diabaikan pada permintaan ini.

Jangan lulus periodStartUnix bersama-sama dengan tahun atau bulan — API mengembalikan 400. Mod listBillingCycles adalah berasingan dan mengabaikan param lain.

Senaraikan tempoh pengebilan

Gunakan ini untuk mengisi lungsur turun tetingkap langganan yang lalu dan semasa (setiap entri ialah periodStartUnix yang anda boleh hantar kembali dengan periodStartUnix=…). Masa tamat tempoh disimpulkan (tempoh seterusnya bermula − 1, atau Stripe current_period_end untuk tempoh aktif).

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

Contoh respons

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

Isih tempoh terbaharu dahulu. Tempoh muncul jika terdapat kunci penggunaan kitaran atau jika ia adalah bil_tempoh_permulaan semasa daripada Stripe webhooks.

Objek kitaran bil

Bentangkan apabila kembangkan termasuk kitaran_bil atau includeBillingCycle ditetapkan. Gunakannya untuk papan pemuka: sempadan pembaharuan, penggunaan dalam tetingkap dan baki kredit yang disertakan.

MedanPenerangan
periodStartUnixMula tetingkap pengebilan (saat unix). Memadankan Stripe current_period_start apabila akaun disegerakkan.
periodEndUnixTamat tetingkap semasa (saat unix), iaitu sejurus sebelum pembaharuan seterusnya — Stripe current_period_end apabila disegerakkan. Tidak sama dengan tarikh pembatalan langganan.
appUsage / apiUsagePenggunaan kredit disertakan dikira dalam tetingkap ini: web/editor (apl) lwn kunci API (api). usedIncludedCredit sama dengan jumlahnya.
includedCreditsElaun kredit (pelan) anda yang disertakan seperti yang disimpan dalam Redis (idea yang sama seperti kredit peringkat atasan).
prepaidCreditsBaki prabayar (dibeli); tidak menetapkan semula setiap tempoh pengebilan.
usedIncludedCreditsJumlah penggunaan yang disertakan dalam tetingkap (apl + API). Penggunaan prabayar tidak ditambah di sini.
remainingIncludedCreditsmaks(0, termasukKredit − digunakanTermasukKredit) untuk petikan ini.
stripeBillingSyncedbenar apabila Redis mempunyai billing_period_start/end daripada Stripe supaya tetingkap sepadan dengan langganan anda; palsu bermakna API kembali ke bulan kalendar UTC untuk blok ini.

Sehingga Stripe webhooks telah menulis tempoh pengebilan untuk pengguna, stripeBillingSynced mungkin palsu dan tetingkap billingCycle mengikuti bulan kalendar UTC. Selepas penyegerakan, had penggunaan pada API imej sejajar dengan kekunci kitaran yang sama.

Untuk "kredit yang digunakan sebelum pembaharuan seterusnya", hubungi expand=billing_cycle dan gunakan billingCycle.periodEndUnix sebagai sempadan pembaharuan, billingCycle.usedIncludedCredits (atau appUsage + apiUsage), dan billingCycle.remainingIncludedCredits. Tambah Kredit prabayar jika anda mahukan jumlah baki boleh guna.

Contoh (cURL)

Penggunaan untuk bulan kalendar UTC tertentu

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

Kitaran pengebilan semasa + blok kitaran pengebilan penuh (diselaraskan pembaharuan apabila disegerakkan)

# 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 tetingkap pengebilan sejarah mengikut permulaan tempoh (daripada 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 kitaran pengebilan)

App_usage dan api_usage peringkat atas sentiasa mencerminkan sama ada bulan kalendar yang diminta atau, apabila periodStartUnix ditetapkan, pembilang kitaran itu. Apabila expand=billing_cycle diabaikan, billingCycle tiada.

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

Apabila stripeBillingSynced adalah benar, billingCycle sepadan dengan penguatkuasaan pada API penyingkiran latar belakang. Apabila palsu, bergantung pada medan bulan kalendar atau tunggu sehingga webhooks mengisi billing_period_* dalam 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