API de eliminación de antecedentes de RemBG: guía de integración y documentos para desarrolladores






OpenAPI · Área de juegos en vivo

Explore la API completa: ejecute solicitudes reales en su navegador

Explore todos los puntos finales, parámetros y respuestas. Pruebe las solicitudes con su clave API y luego obtenga la especificación sin formato en /api/openapi en cualquier momento.

Lanzar referencia interactiva

Instalación 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ón de su entorno: Asegúrese de tener un archivo .env en la raíz de su proyecto que contenga su clave API.

  • Importación de los módulos necesarios: Comience importando la función rembg desde @remove-background-ai/rembg.js y el módulo dotenv para manejar las variables de entorno.

  • Configuración de devoluciones de llamadas de progreso: La biblioteca ofrece devoluciones de llamadas onDownloadProgress y onUploadProgress para realizar un seguimiento del progreso de las operaciones de archivos. En el ejemplo proporcionado, registramos estos eventos directamente en la consola.

Ahora, echemos un vistazo más de cerca a un ejemplo de uso:


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

Recuerde, puede llamar a la función de limpieza si desea eliminar la imagen procesada de su disco después de eliminar el fondo.

Mostrando la barra de progreso

Al integrar un servicio de eliminación en segundo plano, suele resultar beneficioso proporcionar a los usuarios comentarios sobre el progreso de su solicitud de carga o descarga. Para facilitar esto, puede definir sus propias devoluciones de llamada onDownloadProgress y onUploadProgress. Ambas devoluciones de llamada aceptan AxiosProgressEvent como parámetro de evento. A medida que avanza la solicitud, estas devoluciones de llamada se invocan varias veces, lo que le permite, por ejemplo, mostrar una barra de progreso y ajustar su longitud según el progreso.


 (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
					

Uso de membresía y créditos

Devuelve la etiqueta de tu plan, los saldos de crédito incluidos y prepagos, y el uso. Puede realizar consultas por mes calendario UTC (heredado), por período de facturación alineado con Stripe (para monitorear hasta la renovación) o enumerar períodos de facturación conocidos. Autentíquese únicamente con su clave API.

Para esquemas, ejemplos y una consola de prueba, consulte el mismo punto final en la referencia completa: Abrir documentos de API

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

Envíe su clave API: encabezado x-api-key: YOUR_API_KEY_HERE (cree y administre claves en su perfil en rembg.com).

Parámetros de consulta
ParámetroEscribeDescripción
yearnumberAño calendario (1–9999). Con mes, lee Usuario de claves de Redis:{uid}:app_usage:{year}:{month}. Si se omite (y no se utiliza periodStartUnix), el valor predeterminado es el año UTC actual.
monthnumber (1–12)Mes calendario 1–12 (convención UTC utilizada para las claves). Si se omite, el valor predeterminado es el mes UTC actual.
periodStartUnixnumberMarca de tiempo de Unix en segundos: inicio de una ventana de facturación. Lee usuario:{uid}:app_usage:cycle:{periodStartUnix} y api_usage:cycle:…. No se puede combinar con año o mes.
expandstringIndicadores separados por comas. Incluya billing_cycle para agregar un objeto billingCycle: período actual de Stripe cuando billing_period_* existe en Redis; de lo contrario, el mes calendario UTC actual. También funciona con periodStartUnix para una ventana específica.
includeBillingCycle1 / trueIgual que expandir que contiene billing_cycle: configúrelo en 1 o verdadero para incluir el objeto billingCycle.
listBillingCycles1 / trueModo dedicado: listBillingCycles=1 o verdadero devuelve solo { billingCycles: [...] }. Escanea Redis en busca de claves de ciclo para este usuario; otros parámetros de consulta se ignoran en esta solicitud.

No pase periodStartUnix junto con el año o el mes: la API devuelve 400. El modo listBillingCycles es independiente e ignora otros parámetros.

Listar períodos de facturación

Utilice esto para completar un menú desplegable de ventanas de suscripción pasadas y actuales (cada entrada es un periodStartUnix que puede devolver con periodStartUnix=…). Se infieren las horas de finalización del período (inicio del próximo período - 1, o Stripe current_period_end para el período activo).

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

Ejemplo de respuesta

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

Ordenado primero el período más reciente. Aparece un período si hay una clave de uso del ciclo o si es el billing_period_start actual de los webhooks de Stripe.

El objeto billingCycle

Presente cuando se establece expandir incluye billing_cycle o includeBillingCycle. Úselo para paneles: límite de renovación, uso en la ventana y créditos incluidos restantes.

CampoDescripción
periodStartUnixInicio de la ventana de facturación (segundos unix). Coincide con Stripe current_period_start cuando la cuenta está sincronizada.
periodEndUnixFin de la ventana actual (segundos de Unix), es decir, justo antes de la próxima renovación: raya current_period_end cuando se sincroniza. No es lo mismo que la fecha de cancelación de la suscripción.
appUsage / apiUsageEl uso de crédito incluido se cuenta en esta ventana: web/editor (aplicación) frente a clave API (api). usedIncludedCredits es igual a su suma.
includedCreditsSu asignación de crédito incluida (plan) almacenada en Redis (la misma idea que los créditos de nivel superior).
prepaidCreditsSaldo prepago (comprado); no restablece cada período de facturación.
usedIncludedCreditsUso total incluido en la ventana (aplicación + API). Aquí no se suma el consumo prepago.
remainingIncludedCreditsmax(0, incluidosCredits - usedIncludedCredits) para esta instantánea.
stripeBillingSyncedverdadero cuando Redis tiene billing_period_start/end de Stripe para que la ventana coincida con su suscripción; falso significa que la API volvió a un mes calendario UTC para este bloque.

Hasta que los webhooks de Stripe hayan escrito períodos de facturación para el usuario, stripeBillingSynced puede ser falso y la ventana billingCycle sigue el mes calendario UTC. Después de la sincronización, los límites de uso de la API de imágenes se alinean con las mismas claves de ciclo.

Para "créditos utilizados antes de la próxima renovación", llame con expand=billing_cycle y use billingCycle.periodEndUnix como límite de renovación, billingCycle.usedIncludedCredits (o appUsage + apiUsage) y billingCycle.remainingIncludedCredits. Agregue créditos prepagos si desea un saldo total disponible.

Ejemplos (cURL)

Uso para un mes calendario UTC específico

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

Ciclo de facturación actual + bloque de ciclo de facturación completo (renovación alineada cuando se sincroniza)

# 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 ventana de facturación histórica por inicio de período (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'
Ejemplo JSON (con ciclo de facturación)

app_usage y api_usage de nivel superior siempre reflejan el mes calendario solicitado o, cuando se configura periodStartUnix, los contadores de ese ciclo. Cuando se omite expand=billing_cycle, billingCycle está ausente.

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

Cuando stripeBillingSynced es verdadero, billingCycle coincide con la aplicación de la API de eliminación en segundo plano. Cuando sea falso, confíe en los campos del mes calendario o espere hasta que los webhooks completen billing_period_* en 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