Background Removal API

Remove backgrounds from images with our simple, powerful API endpoint.

POSThttps://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.

Request
multipart/form-data

Headers

NameTypeRequiredDescription
x-api-keyStringYesYour API key
Content-TypeStringYesMust be multipart/form-data

Parameters

NameTypeRequiredDescription
fileFileYesThe image file to process (JPEG, PNG, WebP)
modeStringNoProcessing mode: 'fast', 'balanced', or 'quality' (default: 'balanced')
outputFormatStringNoOutput format: 'png' or 'webp' (default: 'webp')
includeMaskBooleanNoInclude alpha mask in output (default: true)
smoothEdgesBooleanNoApply edge smoothing (default: true)
preserveShadowsBooleanNoAttempt 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

NameDescription
Content-Typeimage/png or image/webp (depending on outputFormat)
x-user-emailThe email associated with your API key
x-user-creditsRemaining credits in your account
x-request-idUnique identifier for this request
x-processing-timeProcessing time in milliseconds

Error Responses

When an error occurs, the API returns a JSON object with an error message.

Status CodeErrorDescription
400Bad RequestMissing required fields or invalid parameters
401UnauthorizedMissing or invalid API key
403ForbiddenInsufficient credits to complete the request
429Too Many RequestsRate limit exceeded (100 requests per minute)
500Internal Server ErrorServer-side error processing the request

Error Response Format

{
  "error": "Error message description"
}

Code Examples

javascript
// 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

Fastest

Optimized for speed with good quality on simple images.

  • Best for simple images
  • Ideal for batch processing
Default

Balanced

Recommended

Good trade-off between speed and quality for most use cases.

  • Best for most images
  • Good edge detection

Quality

Highest Quality

Maximum 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

Next Steps