API Documentation

Integrate AI-powered background removal into your applications with our simple REST API

Getting Started

The FreeBgRemover API allows you to integrate AI-powered background removal into your applications. Our API is RESTful, returns JSON responses, and uses standard HTTP response codes.

Base URL

https://api.freebgremover.com/v1

Quick Start

  1. Create an account and get your API key from the dashboard
  2. Make a POST request to /remove-background
  3. Include your image and API key in the request
  4. Receive the processed image with transparent background

Supported Formats

Input: JPEG, PNG, WebP
Output: PNG with transparency
Max size: 25MB per image
Max resolution: 4096x4096px

Authentication

The API uses API keys for authentication. Include your API key in the request headers.

Header Authentication

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

API Key Security

Keep your API key secure and never expose it in client-side code. Use environment variables or secure credential storage.

API Reference

Remove Background

Remove the background from a single image and return the processed image with a transparent background.

POST /remove-background

Request Parameters

Parameter Type Required Description
image File Required The image file to process (JPEG, PNG, WebP)
format String Optional Output format: "png" or "webp" (default: "png")
quality Integer Optional Output quality 1-100 (default: 85)
crop Boolean Optional Auto-crop to subject bounds (default: false)

Example Request

curl -X POST "https://api.freebgremover.com/v1/remove-background" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@/path/to/your/image.jpg" \
  -F "format=png" \
  -F "quality=90" \
  -F "crop=true"

Example Response

{
  "success": true,
  "data": {
    "result_url": "https://cdn.freebgremover.com/processed/abc123.png",
    "original_size": {
      "width": 1024,
      "height": 768
    },
    "processed_size": {
      "width": 1024,
      "height": 768
    },
    "processing_time": 2.34,
    "credits_used": 1
  }
}

Batch Processing

Process multiple images in a single request. Returns a job ID that you can use to check the processing status.

POST /batch-process

Example Request

curl -X POST "https://api.freebgremover.com/v1/batch-process" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "images[]=@/path/to/image1.jpg" \
  -F "images[]=@/path/to/image2.jpg" \
  -F "images[]=@/path/to/image3.jpg" \
  -F "webhook_url=https://your-site.com/webhook"

Example Response

{
  "success": true,
  "data": {
    "job_id": "batch_abc123def456",
    "total_images": 3,
    "estimated_completion": "2024-01-15T10:30:45Z",
    "status_url": "https://api.freebgremover.com/v1/jobs/batch_abc123def456"
  }
}

Job Status

Check the status of a batch processing job.

GET /jobs/{job_id}

Example Response

{
  "success": true,
  "data": {
    "job_id": "batch_abc123def456",
    "status": "completed",
    "progress": {
      "total": 3,
      "completed": 3,
      "failed": 0
    },
    "results": [
      {
        "original_filename": "image1.jpg",
        "result_url": "https://cdn.freebgremover.com/processed/result1.png",
        "status": "success"
      },
      {
        "original_filename": "image2.jpg",
        "result_url": "https://cdn.freebgremover.com/processed/result2.png",
        "status": "success"
      }
    ]
  }
}

Rate Limits

API requests are rate-limited based on your subscription plan to ensure fair usage and optimal performance.

Free Plan

  • • 50 requests/day
  • • 5 requests/minute
  • • Single image only

Pro Plan

  • • 1,000 requests/day
  • • 20 requests/minute
  • • Batch processing

Enterprise

  • • Custom limits
  • • Priority processing
  • • Dedicated support

Rate Limit Headers

Check the response headers for rate limit information: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Error Handling

The API uses standard HTTP response codes and returns detailed error information in JSON format.

HTTP Status Codes

200 Success
400 Bad Request
401 Unauthorized
429 Rate Limited
500 Server Error

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_IMAGE_FORMAT",
    "message": "Unsupported image format",
    "details": "Only JPEG, PNG, and WebP formats are supported"
  }
}

SDKs & Libraries

Official SDKs and community libraries to integrate FreeBgRemover API into your applications.

Python

Official Python SDK with async support

pip install freebgremover

JavaScript

Node.js SDK with TypeScript support

npm install freebgremover-js

PHP

Composer package for PHP applications

composer require freebgremover/php-sdk

Code Examples

Ready-to-use code snippets in popular programming languages.

Python

import requests

# Remove background from image
def remove_background(image_path, api_key):
    url = "https://api.freebgremover.com/v1/remove-background"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    with open(image_path, 'rb') as image_file:
        files = {"image": image_file}
        data = {"format": "png", "quality": 90}
        
        response = requests.post(url, headers=headers, files=files, data=data)
        
        if response.status_code == 200:
            result = response.json()
            return result['data']['result_url']
        else:
            print(f"Error: {response.text}")
            return None

# Usage
api_key = "your_api_key_here"
result_url = remove_background("path/to/image.jpg", api_key)
print(f"Processed image: {result_url}")

JavaScript (Node.js)

const fs = require('fs');
const FormData = require('form-data');
const axios = require('axios');

async function removeBackground(imagePath, apiKey) {
  const form = new FormData();
  form.append('image', fs.createReadStream(imagePath));
  form.append('format', 'png');
  form.append('quality', '90');

  try {
    const response = await axios.post(
      'https://api.freebgremover.com/v1/remove-background',
      form,
      {
        headers: {
          'Authorization': `Bearer ${apiKey}`,
          ...form.getHeaders()
        }
      }
    );

    return response.data.data.result_url;
  } catch (error) {
    console.error('Error:', error.response.data);
    return null;
  }
}

// Usage
const apiKey = 'your_api_key_here';
removeBackground('path/to/image.jpg', apiKey)
  .then(url => console.log('Processed image:', url));

cURL

#!/bin/bash

# Remove background using cURL
curl -X POST "https://api.freebgremover.com/v1/remove-background" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@/path/to/your/image.jpg" \
  -F "format=png" \
  -F "quality=90" \
  -F "crop=true" \
  -o response.json

# Parse the result URL
result_url=$(cat response.json | jq -r '.data.result_url')
echo "Processed image: $result_url"

# Download the processed image
curl -o processed_image.png "$result_url"

Changelog

Recent updates and improvements to the FreeBgRemover API.

v1.3.0

Latest

Released January 15, 2024

  • • Added WebP output format support
  • • Improved processing speed by 30%
  • • Enhanced edge detection for better results
  • • Added auto-crop functionality

v1.2.0

Released December 10, 2023

  • • Introduced batch processing endpoint
  • • Added webhook support for async processing
  • • Increased maximum file size to 25MB
  • • Added detailed error responses

v1.1.0

Released November 5, 2023

  • • Added quality parameter for output control
  • • Improved API response times
  • • Enhanced rate limiting headers
  • • Bug fixes and stability improvements