API d'eliminació de fons de RemBG: documentació per a desenvolupadors i guia d'integració






OpenAPI · Parc infantil en directe

Exploreu l'API completa: executeu sol·licituds reals al vostre navegador

Exploreu tots els punts finals, paràmetres i respostes. Proveu les sol·licituds amb la vostra clau d'API i, a continuació, obteniu l'especificació en brut a /api/openapi en qualsevol moment.

Inicia la referència interactiva

Instal·lació de 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")
  • Configuració del vostre entorn: Assegureu-vos que teniu un fitxer .env a l'arrel del vostre projecte que conté la vostra clau API.

  • Importació dels mòduls necessaris: Comenceu per importar la funció rembg des de @remove-background-ai/rembg.js i el mòdul dotenv per gestionar les variables d'entorn.

  • Configuració de les devolució de trucades de progrés: La biblioteca ofereix trucades onDownloadProgress i onUploadProgress per fer un seguiment del progrés de les operacions dels fitxers. A l'exemple proporcionat, registrem aquests esdeveniments directament a la consola.

Ara, fem una ullada més de prop a una mostra d'ús:


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

Recordeu que la funció de neteja es pot cridar si voleu eliminar la imatge processada del vostre disc després d'eliminar el fons.

Mostra la barra de progrés

Quan s'integra un servei d'eliminació de fons, sovint és beneficiós oferir als usuaris comentaris sobre el progrés de la seva sol·licitud de càrrega o descàrrega. Per facilitar-ho, podeu definir les vostres pròpies trucades onDownloadProgress i onUploadProgress. Ambdues devolucions de trucada accepten AxiosProgressEvent com a paràmetre d'esdeveniment. A mesura que avança la sol·licitud, aquestes devolucions de trucada s'invoquen diverses vegades, cosa que us permet, per exemple, mostrar una barra de progrés i ajustar-ne la durada en funció del progrés.


 (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
					

Ús de membres i crèdits

Retorna l'etiqueta del pla, els saldos de crèdit inclosos i prepagats i l'ús. Podeu consultar per mes natural UTC (heretat), per període de facturació alineat amb Stripe (per al seguiment mitjançant la renovació) o llistar els períodes de facturació coneguts. Autentiqueu-vos només amb la vostra clau API.

Per a esquemes, exemples i una consola de prova, vegeu el mateix punt final a la referència completa: Obre els documents de l'API

Punt final
GET https://www.rembg.com/api/membership-usage
Autenticació

Envieu la vostra clau API: capçalera x-api-key: YOUR_API_KEY_HERE (creeu i gestioneu les claus al vostre perfil a rembg.com).

Paràmetres de consulta
ParàmetreEscriviuDescripció
yearnumberAny natural (1–9999). Amb el mes, llegeix les claus Redis user:{uid}:app_usage:{year}:{month}. Si s'omet (i no s'utilitza periodStartUnix), el valor predeterminat és l'any UTC actual.
monthnumber (1–12)Mes del calendari 1-12 (convenció UTC utilitzada per a les claus). Si s'omet, el valor predeterminat és el mes UTC actual.
periodStartUnixnumberMarca de temps Unix en segons: inici d'una finestra de facturació. Llegeix user:{uid}:app_usage:cycle:{periodStartUnix} i api_usage:cycle:.... No es pot combinar amb any o mes.
expandstringBanderes separades per comes. Inclou billing_cycle per afegir un objecte billingCycle: període actual de Stripe quan billing_period_* existeix a Redis, en cas contrari, el mes calendari UTC actual. També funciona amb periodStartUnix per a una finestra específica.
includeBillingCycle1 / trueIgual que expand que conté billing_cycle: s'estableix en 1 o true per incloure l'objecte billingCycle.
listBillingCycles1 / trueMode dedicat: listBillingCycles=1 o true només retorna { billingCycles: [...] }. Busca en Redis les claus de cicle d'aquest usuari; els altres paràmetres de consulta s'ignoren en aquesta sol·licitud.

No passeu periodStartUnix juntament amb l'any o el mes: l'API retorna 400. El mode listBillingCycles és independent i ignora altres paràmetres.

Llista els períodes de facturació

Utilitzeu-ho per omplir un menú desplegable de les finestres de subscripció anteriors i actuals (cada entrada és un periodStartUnix que podeu tornar amb periodStartUnix=…). S'infereixen els temps de finalització del període (inici del període següent - 1, o Stripe current_period_end per al període actiu).

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

Exemple de resposta

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

Primer s'ha ordenat el període més recent. Apareix un període si hi ha una clau d'ús de cicle o si és el billing_period_start actual dels webhooks de Stripe.

L'objecte billingCycle

Presentar quan s'estableix l'expansió inclou billing_cycle o includeBillingCycle. Utilitzeu-lo per als taulers: límit de renovació, ús a la finestra i crèdits inclosos restants.

CampDescripció
periodStartUnixInici de la finestra de facturació (segons Unix). Coincideix amb Stripe current_period_start quan el compte es sincronitza.
periodEndUnixFinal de la finestra actual (segons Unix), és a dir, just abans de la propera renovació — Stripe current_period_end quan es sincronitzi. No és el mateix que la data de cancel·lació de la subscripció.
appUsage / apiUsageL'ús del crèdit inclòs es compta en aquesta finestra: web/editor (aplicació) i clau API (api). usedIncludedCredits és igual a la seva suma.
includedCreditsEl vostre crèdit inclòs (pla) tal com s'emmagatzema a Redis (la mateixa idea que els crèdits de primer nivell).
prepaidCreditsSaldo prepagat (comprat); no restableix cada període de facturació.
usedIncludedCreditsÚs total inclòs a la finestra (aplicació + API). El consum de prepagament no s'afegeix aquí.
remainingIncludedCreditsmàxim (0, crèdits inclosos − crèdits inclosos inclosos) per a aquesta instantània.
stripeBillingSyncedtrue quan Redis té billing_period_start/end des de Stripe perquè la finestra coincideixi amb la vostra subscripció; false significa que l'API va tornar a un mes natural UTC per a aquest bloc.

Fins que els webhooks de Stripe hagin escrit períodes de facturació per a l'usuari, stripeBillingSynced pot ser fals i la finestra billingCycle segueix el mes natural UTC. Després de la sincronització, els límits d'ús de l'API d'imatge s'alineen amb les mateixes claus de cicle.

Per als "crèdits utilitzats abans de la propera renovació", truqueu amb expand=billing_cycle i utilitzeu billingCycle.periodEndUnix com a límit de renovació, billingCycle.usedIncludedCredits (o appUsage + apiUsage) i billingCycle.remainingIncludedCredits. Afegiu crèdits prepagats si voleu el saldo total disponible.

Exemples (cURL)

Ús per a un mes calendari UTC específic

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

Cicle de facturació actual + bloc de cicle de facturació complet (alineat amb la renovació quan es sincronitza)

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

Una finestra de facturació històrica per període d'inici (de listBillingCycles o 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'
Exemple de JSON (amb cicle de facturació)

L'ús de l'aplicació i l'ús de l'api de nivell superior sempre reflecteixen el mes natural sol·licitat o, quan s'estableix periodStartUnix, els comptadors d'aquest cicle. Quan s'omet expand=billing_cycle, no hi ha 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
  }
}

Quan stripeBillingSynced és cert, billingCycle coincideix amb l'aplicació de l'API d'eliminació de fons. Quan sigui fals, confieu en els camps del mes natural o espereu fins que els webhooks omplin billing_period_* a 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