API ya Uondoaji Asili ya RemBG - Hati za Wasanidi Programu na Mwongozo wa Ujumuishaji

OpenAPI · Uwanja wa michezo wa moja kwa moja

Chunguza API kamili—tekeleza maombi halisi katika kivinjari chako

Vinjari kila ncha, vigezo na majibu. Jaribu maombi ukitumia ufunguo wako wa API, kisha unyakue alama mbichi kwenye /api/openapi wakati wowote.

Zindua marejeleo shirikishi

Usakinishaji wa rembg.js


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

Parameter	Type	Required	Default	Description
apiKey	string	Required	–	Your Rembg API key
inputImage	string \| 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.format	webp (default) \| png	Optional	webp	Specifies the output image format. Either "webp" (default) or "png"
options.returnBase64	boolean	Optional	false	Return Base64 string instead of file
options.returnMask	boolean	Optional	false	Return only the alpha mask
options.w	number	Optional	–	Target width (maintains aspect ratio)
options.h	number	Optional	–	Target height (maintains aspect ratio)
options.exact_resize	boolean	Optional	false	Force exact width × height (may distort)
options.angle	number	Optional	0	Rotation angle in degrees
options.expand	boolean	Optional	true	Add padding so rotated images aren’t cropped
options.bg_color	string	Optional	-	Optional solid background color in hex (e.g. #FFFFFFFF) or named color (e.g. "red", "blue")

Kuweka Mazingira Yako: Hakikisha kuwa una faili ya .env kwenye msingi wa mradi wako iliyo na ufunguo wako wa API.
Kuagiza Moduli Muhimu: Anza kwa kuleta kitendakazi cha rembg kutoka @remove-background-ai/rembg.js na moduli ya dotenv ili kushughulikia vigeuzo vya mazingira.
Kusanidi Simu za Maendeleo: Maktaba inatoa onDownloadProgress na onUploadProgress callbacks kufuatilia maendeleo ya uendeshaji wa faili. Katika mfano uliotolewa, tunaweka matukio haya moja kwa moja kwenye kiweko.

Sasa, hebu tuangalie kwa karibu sampuli ya matumizi:


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

Kumbuka, kipengele cha kusafisha kinaweza kuitwa ikiwa ungependa kuondoa picha iliyochakatwa kutoka kwa diski yako baada ya kuondolewa kwa usuli.

Inaonyesha upau wa Maendeleo

Unapojumuisha huduma ya kuondoa usuli, mara nyingi ni vyema kuwapa watumiaji maoni kuhusu maendeleo ya ombi lao la kupakia au kupakua. Ili kuwezesha hili, unaweza kufafanua simu zako za onDownloadProgress na onUploadProgress. Simu hizi zote mbili zinakubali AxiosProgressEvent kama kigezo cha tukio. Kadiri ombi linavyoendelea, simu hizi za kurudisha nyuma huimbwa mara nyingi, huku kuruhusu, kwa mfano, kuonyesha upau wa maendeleo na kurekebisha urefu wake kulingana na maendeleo.


 (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

Curl


# Full example: upload an image and remove its background with all optional parameters
curl -X POST "https://api.rembg.com/rmbg"
  -H "x-api-key: YOUR_API_KEY_HERE"          # your personal API key
  -F "image=@/path/to/image.jpg"             # input image file
  -F "format=webp"                           # output format: webp (default) or png
  -F "w=800"                                 # target width in pixels (maintains aspect ratio unless exact_resize=true)
  -F "h=600"                                 # target height in pixels
  -F "exact_resize=false"                    # true = force exact w × h, may distort
  -F "mask=false"                            # true = return only the alpha mask instead of full image
  -F "bg_color=#ffffffff"                    # optional solid background color (RGBA hex)
  -F "angle=0"                               # rotate the image by given degrees after processing
  -F "expand=true"                           # add padding so rotated images don’t get cropped

HTTP


POST /rmbg HTTP/1.1
Host: api.rembg.com
x-api-key: YOUR_API_KEY_HERE
Content-Type: multipart/form-data; boundary=----BOUNDARY

------BOUNDARY
Content-Disposition: form-data; name="image"; filename="image.jpg"
Content-Type: image/jpeg
<binary data of your image goes here>
------BOUNDARY
Content-Disposition: form-data; name="format"
webp
------BOUNDARY
Content-Disposition: form-data; name="w"
800
------BOUNDARY
Content-Disposition: form-data; name="h"
600
------BOUNDARY
Content-Disposition: form-data; name="exact_resize"
false
------BOUNDARY
Content-Disposition: form-data; name="mask"
false
------BOUNDARY
Content-Disposition: form-data; name="bg_color"
#ffffffff
------BOUNDARY
Content-Disposition: form-data; name="angle"
0
------BOUNDARY
Content-Disposition: form-data; name="expand"
true
------BOUNDARY--

Python Requests


import requests

# Endpoint URL for the background-removal API
url = "https://api.rembg.com/rmbg"

# Required API key header
headers = {
    "x-api-key": "YOUR_API_KEY_HERE"
}

# The image file to process (opened in binary mode)
files = {
    "image": open("/path/to/image.jpg", "rb")
}

# Optional form fields supported by your backend.
# Adjust values as needed; any of these can be omitted.
data = {
    "format": "webp",         # Output format: "webp" (default) or "png"
    "w": 800,                 # Target width (maintains aspect ratio unless exact_resize is true)
    "h": 600,                 # Target height
    "exact_resize": "false",  # "true" forces exact w×h, may distort
    "mask": "false",          # "true" returns only the alpha mask
    "bg_color": "#ffffffff",  # Optional solid background color (RGBA hex)
    "angle": 0,               # Rotation angle in degrees
    "expand": "true",         # Add padding so rotated images aren’t cropped
}

# Send the POST request with headers, file, and extra form data
response = requests.post(url, headers=headers, files=files, data=data)

# Handle the response
if response.status_code == 200:
    # Save the processed image to disk
    with open("output.webp", "wb") as f:
        f.write(response.content)
    print("Background removed successfully → saved as output.webp")
else:
    # Print error details if the request failed
    print("Error:", response.status_code, response.text)

Matumizi ya Uanachama na Mikopo

Hurejesha lebo ya mpango wako, salio la mkopo lililojumuishwa na linalolipiwa mapema, na matumizi. Unaweza kuuliza swali kufikia mwezi wa kalenda ya UTC (urithi), kwa kipindi cha bili kilichopangwa kwa Mistari (kwa ufuatiliaji kupitia kusasisha), au kuorodhesha vipindi vya bili vinavyojulikana. Thibitisha kwa ufunguo wako wa API pekee.

Kwa michoro, mifano, na dashibodi ya kujaribu, angalia ncha sawa katika marejeleo kamili: Fungua hati za API

Mwisho

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

Uthibitishaji

Tuma ufunguo wako wa API: kichwa x-api-key: YOUR_API_KEY_HERE (unda na udhibiti funguo katika wasifu wako kwenye rembg.com).

Vigezo vya hoja

Kigezo	Aina	Maelezo
year	number	Mwaka wa Kalenda (1–9999). Katika mwezi, mtumiaji wa funguo za Redis husoma:{uid}:app_usage:{year}:{month}. Ikiwa imeachwa (na periodStartUnix haitumiki), chaguomsingi kwa mwaka wa sasa wa UTC.
month	number (1–12)	Kalenda ya mwezi wa 1–12 (mkataba wa UTC hutumika kwa funguo). Ikiondolewa, chaguomsingi kwa mwezi wa sasa wa UTC.
periodStartUnix	number	Muhuri wa muda wa Unix kwa sekunde: mwanzo wa dirisha la bili. Husoma mtumiaji:{uid}:app_usage:cycle:{periodStartUnix} na api_usage:cycle:…. Haiwezi kuunganishwa na mwaka au mwezi.
expand	string	Bendera zilizotenganishwa kwa koma. Jumuisha billing_cycle ili kuongeza kitu cha billingCycle: kipindi cha sasa cha Stripe wakati billing_period_* ipo katika Redis, vinginevyo mwezi wa sasa wa kalenda ya UTC. Pia inafanya kazi na periodStartUnix kwa dirisha maalum.
includeBillingCycle	1 / true	Sawa na kupanua iliyo na billing_cycle: imewekwa kuwa 1 au kweli ili kujumuisha kitu cha billingCycle.
listBillingCycles	1 / true	Hali maalum: listBillingCycles=1 au marejesho ya kweli pekee { billingCycles: [...] }. Inachanganua Redis kwa funguo za mzunguko kwa mtumiaji huyu; vigezo vingine vya hoja vinapuuzwa kwa ombi hili.

Usipite periodStartUnix pamoja na mwaka au mwezi - API inarejesha 400. Hali ya listBillingCycles ni tofauti na inapuuza vigezo vingine.

Orodhesha vipindi vya bili

Tumia hii kujaza menyu kunjuzi ya madirisha ya usajili yaliyopita na ya sasa (kila ingizo ni periodStartUnix unaweza kurudishwa na periodStartUnix=…). Nyakati za mwisho za kipindi zimekisiwa (kipindi kijacho huanza − 1, au mwisho wa kipindi cha sasa cha Stripe kwa kipindi amilifu).

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

Mfano wa jibu

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

Panga kipindi kipya zaidi kwanza. Kipindi kinaonekana ikiwa kuna ufunguo wa matumizi ya mzunguko au ikiwa ni billing_period_start ya sasa kutoka kwa Stripe webhooks.

Kitu cha Mzunguko wa bili

Wasilisha wakati upanuzi unajumuisha billing_cycle au includeBillingCycle imewekwa. Itumie kwa dashibodi: mpaka wa kusasisha, matumizi kwenye dirisha, na mikopo iliyosalia iliyojumuishwa.

Sehemu	Maelezo
periodStartUnix	Mwanzo wa dirisha la bili (sekunde moja). Inalinganisha Stripe current_period_start wakati akaunti inasawazishwa.
periodEndUnix	Mwisho wa kidirisha cha sasa (sekunde moja), yaani, kabla tu ya usasishaji unaofuata - Mwisho_wa_muda_wa mstari wakati kulandanishwa. Sio sawa na tarehe ya kughairi usajili.
appUsage / apiUsage	Matumizi ya mkopo yaliyojumuishwa katika dirisha hili: wavuti/kihariri (programu) dhidi ya ufunguo wa API (api). usedIncludedCredits ni sawa na jumla yao.
includedCredits	Posho yako ya mkopo iliyojumuishwa (ya mpango) kama ilivyohifadhiwa katika Redis (wazo sawa na mikopo ya kiwango cha juu).
prepaidCredits	Salio la kulipia kabla (lililonunuliwa); haiweki upya kila kipindi cha bili.
usedIncludedCredits	Jumla ya matumizi imejumuishwa kwenye dirisha (programu + API). Matumizi ya kulipia kabla hayajaongezwa hapa.
remainingIncludedCredits	max(0, pamoja naMikopo - usedIncludedCredits) kwa muhtasari huu.
stripeBillingSynced	ni kweli wakati Redis ina billing_period_start/end kutoka Stripe ili dirisha lilingane na usajili wako; uwongo inamaanisha kuwa API ilirejea kwa mwezi wa kalenda ya UTC kwa kizuizi hiki.

Hadi Stripe webbhooks zimeandika vipindi vya bili kwa mtumiaji, stripeBillingSynced inaweza kuwa ya uwongo na dirisha la billingCycle litafuata mwezi wa kalenda ya UTC. Baada ya kusawazisha, vikomo vya matumizi kwenye API ya picha vinalingana na vitufe sawa vya mzunguko.

Kwa "mikopo iliyotumika kabla ya kusasishwa tena", piga simu kwa expand=billing_cycle na utumie billingCycle.periodEndUnix kama mpaka wa kufanya upya, billingCycle.usedIncludedCredits (au appUsage + apiUsage), na billingCycle.remainingIncludedCredits. Ongeza Mikopo ya kulipia kabla ikiwa unataka salio la jumla linaloweza kutumika.

Mifano (cURL)

Matumizi kwa mwezi mahususi wa kalenda ya UTC

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

Mzunguko wa sasa wa utozaji + uzuiaji kamili wa bili (urekebishaji umewekwa wakati kulandanishwa)

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

Dirisha moja la kihistoria la utozaji kwa kuanza kwa kipindi (kutoka kwa listBillingCycles au 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'

Mfano JSON (pamoja na mzunguko wa bili)

Matumizi_ya kiwango cha juu cha programu na api_matumizi kila wakati huakisi ama mwezi wa kalenda ulioombwa au, periodStartUnix inapowekwa, kaunta za mzunguko huo. Wakati expand=billing_cycle imeachwa, billingCycle haipo.

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

Wakati stripeBillingSynced ni kweli, billingCycle inalingana na utekelezaji kwenye API ya uondoaji wa usuli. Ikiwa sivyo, tegemea sehemu za mwezi wa kalenda au subiri hadi viboreshaji vya mtandao vijaze billing_period_* katika 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
}

Multiple Validation Errors Response