RemBG Arka Plan Kaldırma API'si – Geliştirici Belgeleri ve Entegrasyon Kılavuzu






OpenAPI · Canlı oyun alanı

API'nin tamamını keşfedin; tarayıcınızda gerçek istekleri çalıştırın

Her uç noktaya, parametreye ve yanıta göz atın. API anahtarınızla istekleri deneyin, ardından istediğiniz zaman /api/openapi adresinden ham spesifikasyonu alın.

Etkileşimli referansı başlat

rembg.js'nin kurulumu

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")
  • Ortamınızı Kurma: Proje kökünüzde API anahtarınızı içeren bir .env dosyanızın olduğundan emin olun.

  • Gerekli Modülleri İçe Aktarma: Ortam değişkenlerini yönetmek için @remove-background-ai/rembg.js adresinden rembg işlevini ve dotenv modülünü içe aktararak başlayın.

  • İlerleme Durumu Geri Aramalarını Yapılandırma: Kitaplık, dosya işlemlerinin ilerlemesini izlemek için onDownloadProgress ve onUploadProgress geri çağrılarını sunar. Verilen örnekte, bu olayları doğrudan konsola kaydediyoruz.

Şimdi örnek kullanıma daha yakından bakalım:


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

Unutmayın, arka plan kaldırıldıktan sonra işlenen görüntüyü diskinizden kaldırmak istiyorsanız temizleme işlevinin çağrılabileceğini unutmayın.

İlerleme çubuğu gösteriliyor

Bir arka plan kaldırma hizmetini entegre ederken, kullanıcılara yükleme veya indirme isteklerinin ilerleyişi hakkında geri bildirim sağlamak genellikle yararlı olur. Bunu kolaylaştırmak için kendi onDownloadProgress ve onUploadProgress geri çağrılarınızı tanımlayabilirsiniz. Bu geri çağırmaların her ikisi de AxiosProgressEvent'i bir olay parametresi olarak kabul eder. İstek ilerledikçe, bu geri aramalar birden çok kez başlatılır; bu, örneğin bir ilerleme çubuğu görüntülemenize ve ilerlemeye bağlı olarak uzunluğunu ayarlamanıza olanak tanır.


 (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
					

Üyelik ve Kredi Kullanımı

Plan etiketinizi, dahil olan ve ön ödemeli kredi bakiyelerinizi ve kullanımınızı döndürür. UTC takvim ayına (eski), Stripe uyumlu fatura dönemine (yenileme yoluyla izleme için) göre sorgulama yapabilir veya bilinen fatura dönemlerini listeleyebilirsiniz. Yalnızca API anahtarınızla kimlik doğrulaması yapın.

Şemalar, örnekler ve deneme konsolu için tam referansta aynı uç noktaya bakın: API belgelerini aç

Uç nokta
GET https://www.rembg.com/api/membership-usage
Kimlik Doğrulama

API anahtarınızı gönderin: başlık x-api-key: YOUR_API_KEY_HERE (rembg.com'daki profilinizde anahtarlar oluşturun ve yönetin).

Sorgu parametreleri
ParametreTürAçıklama
yearnumberTakvim yılı (1–9999). Ay ile Redis anahtarlarını okur user:{uid}:app_usage:{year}:{month}. Atlanırsa (ve periodStartUnix kullanılmazsa), varsayılan olarak geçerli UTC yılı kullanılır.
monthnumber (1–12)Takvim ayı 1-12 (anahtarlar için kullanılan UTC kuralı). Atlanırsa, varsayılan olarak geçerli UTC ayı kullanılır.
periodStartUnixnumberSaniye cinsinden Unix zaman damgası: faturalandırma penceresinin başlangıcı. user:{uid}:app_usage:cycle:{periodStartUnix} ve api_usage:cycle:…'yi okur. Yıl veya ay ile birleştirilemez.
expandstringVirgülle ayrılmış işaretler. Bir billingCycle nesnesi eklemek için billing_cycle'ı ekleyin: Redis'te billing_period_* mevcut olduğunda geçerli Stripe dönemi, aksi takdirde geçerli UTC takvim ayı. Ayrıca belirli bir pencere için periodStartUnix ile de çalışır.
includeBillingCycle1 / truebilling_cycle'ı içeren genişletmeyle aynı: billingCycle nesnesini dahil etmek için 1'e veya true'ya ayarlayın.
listBillingCycles1 / trueÖzel mod: listBillingCycles=1 veya true yalnızca { billingCycles: [...] } değerini döndürür. Bu kullanıcı için döngü anahtarları için Redis'i tarar; bu istekte diğer sorgu parametreleri dikkate alınmaz.

periodStartUnix'i yıl veya ay ile birlikte geçmeyin — API 400 değerini döndürür. listBillingCycles modu ayrıdır ve diğer parametreleri yok sayar.

Fatura dönemlerini listeleyin

Geçmiş ve mevcut abonelik pencerelerinin açılır listesini doldurmak için bunu kullanın (her giriş, periodStartUnix=… ile geri gönderebileceğiniz bir periodStartUnix'tir). Dönem bitiş zamanları çıkarılır (sonraki dönem başlangıcı - 1 veya etkin dönem için Stripe current_period_end).

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

Örnek yanıt

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

En yeni dönem ilk olarak sıralandı. Bir döngü kullanım anahtarı varsa veya Stripe web kancalarından geçerli billing_period_start ise bir nokta görünür.

billingCycle nesnesi

Genişletme içerir billing_cycle veya includeBillingCycle ayarlandığında mevcuttur. Gösterge tabloları için kullanın: yenileme sınırı, penceredeki kullanım ve kalan dahil edilen krediler.

AlanAçıklama
periodStartUnixFaturalandırma penceresinin başlangıcı (unix saniye). Hesap senkronize edildiğinde Stripe current_period_start ile eşleşir.
periodEndUnixGeçerli pencerenin sonu (unix saniye), yani bir sonraki yenilemeden hemen önce — Senkronize edildiğinde current_period_end'i şeritle. Abonelik iptal tarihi ile aynı değildir.
appUsage / apiUsageBu pencerede sayılan kredi kullanımı dahil: web/düzenleyici (uygulama) ve API anahtarı (api). kullanılanIncludedCredits bunların toplamına eşittir.
includedCreditsRedis'te saklandığı şekliyle dahil edilen (plan) kredi ödeneğiniz (üst düzey kredilerle aynı fikir).
prepaidCreditsÖn ödemeli (satın alınan) bakiye; her fatura dönemini sıfırlamaz.
usedIncludedCreditsPenceredeki toplam dahil edilen kullanım (uygulama + API). Ön ödemeli tüketim buraya eklenmez.
remainingIncludedCreditsmax(0, includeCredits − kullanılmışIncludedCredits).
stripeBillingSynceddoğru, Redis Stripe'tan billing_period_start/end aldığında pencere aboneliğinizle eşleştiğinde doğrudur; false, API'nin bu blok için UTC takvim ayına geri döndüğü anlamına gelir.

Stripe web kancaları kullanıcı için fatura dönemlerini yazana kadar stripeBillingSynced yanlış olabilir ve billingCycle penceresi UTC takvim ayını takip eder. Senkronizasyondan sonra, görüntü API'sindeki kullanım sınırları aynı döngü tuşlarıyla uyumlu hale gelir.

"Bir sonraki yenilemeden önce kullanılan krediler" için, extend=billing_cycle ile çağrı yapın ve yenileme sınırı olarak billingCycle.periodEndUnix'i, billingCycle.usedIncludedCredits'i (veya appUsage + apiUsage) ve billingCycle.remainingIncludedCredits'i kullanın. Toplam harcanabilir bakiye istiyorsanız ön ödemeliKrediler ekleyin.

Örnekler (cURL)

Belirli bir UTC takvim ayına ilişkin kullanım

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

Geçerli faturalandırma döngüsü + tam billingCycle bloğu (senkronizasyon sırasında yenilemeye uygun hale getirilir)

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

Dönem başlangıcına göre bir geçmiş faturalandırma aralığı (listBillingCycles veya Stripe'tan)

# 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'
Örnek JSON (faturalandırma döngüsüyle)

Üst düzey app_usage ve api_usage her zaman istenen takvim ayını veya periodStartUnix ayarlandığında o döngünün sayaçlarını yansıtır. Expand=billing_cycle atlandığında billingCycle yoktur.

{
  "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 doğru olduğunda, billingCycle arka plan kaldırma API'sindeki yaptırımla eşleşir. Yanlış olduğunda takvim ayı alanlarına güvenin veya web kancalarının Redis'te billing_period_* değerini doldurmasını bekleyin.

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