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
Quick Start
- Create an account and get your API key from the dashboard
- Make a POST request to
/remove-background
- Include your image and API key in the request
- Receive the processed image with transparent background
Supported Formats
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.
/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.
/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.
/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
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
LatestReleased 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