Background Removal API
Remove backgrounds from images with our simple, powerful API endpoint.
https://api.versatool.ai/api/remove-background/
Automatically removes the background from an uploaded image, returning the processed image with a transparent background.
Each successful API call consumes 1 credit from your account. You can view your remaining credits in the API response headers.
Requestmultipart/form-data
Headers
Name | Type | Required | Description |
---|---|---|---|
x-api-key | String | Yes | Your API key |
Content-Type | String | Yes | Must be multipart/form-data |
Parameters
Name | Type | Required | Description |
---|---|---|---|
file | File | Yes | The image file to process (JPEG, PNG, WebP) |
mode | String | No | Processing mode: 'fast', 'balanced', or 'quality' (default: 'balanced') |
outputFormat | String | No | Output format: 'png' or 'webp' (default: 'webp') |
includeMask | Boolean | No | Include alpha mask in output (default: true) |
smoothEdges | Boolean | No | Apply edge smoothing (default: true) |
preserveShadows | Boolean | No | Attempt to preserve shadows (default: false) |
Response
The API returns the processed image directly as a binary stream. The content type will be either image/png
or image/webp
depending on the requested output format.
Response Headers
Name | Description |
---|---|
Content-Type | image/png or image/webp (depending on outputFormat) |
x-user-email | The email associated with your API key |
x-user-credits | Remaining credits in your account |
x-request-id | Unique identifier for this request |
x-processing-time | Processing time in milliseconds |
Error Responses
When an error occurs, the API returns a JSON object with an error message.
Status Code | Error | Description |
---|---|---|
400 | Bad Request | Missing required fields or invalid parameters |
401 | Unauthorized | Missing or invalid API key |
403 | Forbidden | Insufficient credits to complete the request |
429 | Too Many Requests | Rate limit exceeded (100 requests per minute) |
500 | Internal Server Error | Server-side error processing the request |
Error Response Format
{
"error": "Error message description"
}
Code Examples
// Using fetch API with FormData
const formData = new FormData();
formData.append('file', imageFile); // Your image file
formData.append('mode', 'balanced');
formData.append('outputFormat', 'png');
formData.append('smoothEdges', 'true');
fetch('https://api.versatool.ai/api/remove-background/', {
method: 'POST',
headers: {
'x-api-key': 'YOUR_API_KEY'
},
body: formData
})
.then(response => {
if (!response.ok) {
throw new Error(`HTTP error! Status: ${response.status}`);
}
// The response is the processed image binary
return response.blob();
})
.then(imageBlob => {
// Use the processed image
const imageUrl = URL.createObjectURL(imageBlob);
console.log('Processed image URL:', imageUrl);
// Example: Update an image element
document.getElementById('outputImage').src = imageUrl;
})
.catch(error => {
console.error('Error:', error);
});
Processing Modes
You can control the trade-off between processing speed and output quality by specifying the mode
parameter.
Fast
FastestOptimized for speed with good quality on simple images.
- Best for simple images
- Ideal for batch processing
Balanced
RecommendedGood trade-off between speed and quality for most use cases.
- Best for most images
- Good edge detection
Quality
Highest QualityMaximum quality optimized for difficult edges and details.
- Best for complex images
- Excellent for hair & fine details
Rate Limits and Quotas
Rate Limits
To ensure reliable performance for all users, we enforce the following rate limits:
- Maximum 100 requests per minute
- Maximum file size: 10MB
- Max dimensions: 4000 x 4000 pixels
Credits
Each API call consumes credits from your account:
- 1 credit per successful background removal
- Failed requests do not consume credits
- Check remaining credits in response headers