API Reference

API Reference

Complete reference for the Bg Remover REST API. All endpoints, parameters, response schemas, and status codes — in one place.

API Version: v1 · Last updated: February 13, 2026

Overview

The Bg Remover API is a RESTful service that accepts JSON requests and returns JSON responses. All communication happens over HTTPS. The API uses standard HTTP methods, status codes, and authentication patterns.

You can send images via URL or as multipart file uploads. Processed images are delivered via our global CDN and are available for download until they expire according to your plan's retention policy.

Base URL

https://api.bgremover.dev

All endpoints are relative to this base URL. For example, the remove background endpoint is at https://api.bgremover.dev/v1/remove

Authentication

Authenticate requests by including your API key in the Authorization header:

Authorization: Bearer bgr_live_your_api_key_here

Generate API keys from your Dashboard. Keep your keys secure — do not commit them to version control or expose them in client-side code.

POST/v1/remove

Remove Background

Remove the background from an image. You can provide either an image URL or upload a file directly using multipart form data.

Parameters

NameTypeRequiredDescription
image_urlstringOptionalURL of the image to process. Must be publicly accessible. Mutually exclusive with file upload.
output_formatstringOptionalDesired output format. Options: png (default), webp, jpeg.
output_qualityintegerOptionalOutput quality (1-100). Applies to WebP and JPEG formats. Default: 90.
bg_colorstringOptionalReplacement background color in hex (e.g., "#FFFFFF"). If omitted, background is transparent.
max_resolutionstringOptionalMaximum output resolution. Options: original, 1080p, 720p, 480p. Default: original.
cropbooleanOptionalAuto-crop the result to the subject bounding box. Default: false.
webhook_urlstringOptionalURL to receive a POST notification when processing completes.

Request Body

{
  "image_url": "https://example.com/photo.jpg",
  "output_format": "png",
  "crop": true,
  "webhook_url": "https://yourapp.com/webhook"
}

Response

{
  "success": true,
  "data": {
    "id": "img_abc123xyz",
    "output_url": "https://cdn.bgremover.dev/results/img_abc123xyz.png",
    "format": "png",
    "width": 1920,
    "height": 1080,
    "original_width": 2400,
    "original_height": 1600,
    "file_size_bytes": 245120,
    "processing_time_ms": 1240,
    "credits_used": 1,
    "expires_at": "2026-02-14T22:30:00Z"
  }
}

Status Codes

200Background successfully removed
400Invalid request parameters
401Missing or invalid API key
413Image exceeds maximum file size
415Unsupported image format
429Rate limit exceeded
POST/v1/remove/batch

Batch Remove Background

Process up to 20 images in a single request. Returns immediately with a batch ID. Results are delivered via webhook or polling.

Parameters

NameTypeRequiredDescription
imagesarrayRequiredArray of objects, each containing an image_url and optional settings.
webhook_urlstringOptionalURL to receive a POST notification when all images in the batch complete.
output_formatstringOptionalDefault output format applied to all images in the batch.

Request Body

{
  "images": [
    { "image_url": "https://example.com/photo1.jpg" },
    { "image_url": "https://example.com/photo2.jpg" },
    { "image_url": "https://example.com/photo3.jpg" }
  ],
  "output_format": "webp",
  "webhook_url": "https://yourapp.com/batch-done"
}

Response

{
  "success": true,
  "data": {
    "batch_id": "batch_def456uvw",
    "total_images": 3,
    "status": "processing",
    "estimated_time_ms": 3600,
    "poll_url": "https://api.bgremover.dev/v1/batch/batch_def456uvw"
  }
}

Status Codes

202Batch accepted for processing
400Invalid request — too many images or invalid URLs
401Missing or invalid API key
429Rate limit exceeded
GET/v1/batch/:batch_id

Get Batch Status

Retrieve the current status and results of a batch processing job. Poll this endpoint to track completion.

Parameters

NameTypeRequiredDescription
batch_idstring (path)RequiredThe batch ID returned by the batch endpoint.

Response

{
  "success": true,
  "data": {
    "batch_id": "batch_def456uvw",
    "status": "completed",
    "total_images": 3,
    "completed": 3,
    "failed": 0,
    "results": [
      {
        "id": "img_001",
        "output_url": "https://cdn.bgremover.dev/results/img_001.webp",
        "processing_time_ms": 1100
      },
      {
        "id": "img_002",
        "output_url": "https://cdn.bgremover.dev/results/img_002.webp",
        "processing_time_ms": 980
      },
      {
        "id": "img_003",
        "output_url": "https://cdn.bgremover.dev/results/img_003.webp",
        "processing_time_ms": 1320
      }
    ]
  }
}

Status Codes

200Batch status retrieved successfully
404Batch ID not found
401Missing or invalid API key
GET/v1/account

Get Account Info

Retrieve your account details including plan type, usage statistics, and remaining credits.

Response

{
  "success": true,
  "data": {
    "id": "usr_abc123",
    "email": "dev@example.com",
    "plan": "pro",
    "credits_remaining": 847,
    "credits_total": 1000,
    "rate_limit": {
      "requests_per_minute": 60,
      "daily_limit": 1000
    },
    "usage_this_month": {
      "images_processed": 153,
      "credits_used": 153,
      "api_calls": 201
    }
  }
}

Status Codes

200Account info retrieved
401Missing or invalid API key
GET/v1/usage

Get Usage Statistics

Retrieve detailed API usage statistics for the current billing period, including daily breakdowns.

Parameters

NameTypeRequiredDescription
start_datestring (ISO 8601)OptionalStart date for the usage period. Default: start of current month.
end_datestring (ISO 8601)OptionalEnd date for the usage period. Default: today.
granularitystringOptionalData granularity. Options: daily, weekly, monthly. Default: daily.

Response

{
  "success": true,
  "data": {
    "period": { "start": "2026-02-01", "end": "2026-02-13" },
    "total_requests": 1482,
    "total_credits_used": 1350,
    "avg_processing_time_ms": 1150,
    "daily": [
      { "date": "2026-02-13", "requests": 142, "credits": 130 },
      { "date": "2026-02-12", "requests": 158, "credits": 148 }
    ]
  }
}

Status Codes

200Usage statistics retrieved
401Missing or invalid API key
DELETE/v1/images/:image_id

Delete Processed Image

Immediately and permanently delete a processed image from our CDN. This action cannot be undone.

Parameters

NameTypeRequiredDescription
image_idstring (path)RequiredThe image ID to delete.

Response

{
  "success": true,
  "data": {
    "id": "img_abc123xyz",
    "deleted": true,
    "deleted_at": "2026-02-13T22:30:00Z"
  }
}

Status Codes

200Image deleted successfully
404Image not found or already deleted
401Missing or invalid API key

Response Format

All API responses follow a consistent JSON envelope:

Success

{
  "success": true,
  "data": { ... }
}

Error

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message"
  }
}

All responses include standard headers: Content-Type: application/json, rate limit headers, and a unique X-Request-ID for debugging.

Rate Limits

Rate limits are tiered by plan. When exceeded, the API returns 429 Too Many Requests.

PlanRequests/minDaily LimitMax File SizeRetention
Free105010 MB24 hours
Pro601,00025 MB7 days
Enterprise200Unlimited50 MB30 days

Rate Limit Headers

X-RateLimit-Limit: 60          # Max requests per window
X-RateLimit-Remaining: 45      # Remaining requests
X-RateLimit-Reset: 1708300800  # Unix timestamp when limit resets
Retry-After: 30                # Seconds to wait (only on 429)