RemovAI - API Documentation

Introduction

The RemovAI API allows you to programmatically remove backgrounds from images. This powerful tool can be integrated into your applications, websites, or automated workflows to process images at scale.

Our API provides several endpoints for removing backgrounds from images provided as URLs or uploaded files, retrieving processed images, and managing your image library.

Base URL

All API requests should be made to the following base URL:

https://api.removai.com/v1

Request Format

The API accepts request data in JSON format for most endpoints. For file uploads, use multipart/form-data.

Response Format

All responses are returned in JSON format with the following structure:

{
  "success": true,
  "data": {
    // Response data varies by endpoint
  },
  "meta": {
    // Pagination or additional information
  }
}

Getting Your API Key

To use the RemovAI API, you'll need an API key. You can obtain one by signing up for a RemovAI account and navigating to the API section in your dashboard.

We offer different subscription plans with varying API usage limits. Visit our pricing page for more information.

Learn About Authentication →

Authentication

The RemovAI API uses API keys for authentication. All API requests must include your API key in the request headers.

API Key Authentication

Include your API key in the X-API-Key header:

X-API-Key: your_api_key_here

Example Request with Authentication

curl -X POST https://api.removai.com/v1/remove-background \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/image.jpg"}'

Security Best Practices

Keep your API key secure and never expose it in client-side code.
Use environment variables to store your API key in your applications.
If you suspect your API key has been compromised, you can regenerate it from your dashboard.

Rate Limits

To ensure the stability of our service, we apply rate limits to API requests based on your subscription plan:

Plan	Rate Limit	Monthly Quota
Basic	10 requests per minute	50 images per month
Pro	60 requests per minute	500 images per month
Enterprise	300 requests per minute	Unlimited

Rate Limit Headers

Each API response includes the following headers to help you track your rate limit usage:

Header	Description
X-RateLimit-Limit	The maximum number of requests you can make per minute
X-RateLimit-Remaining	The number of requests remaining in the current rate limit window
X-RateLimit-Reset	The time at which the current rate limit window resets (UTC epoch seconds)

Exceeding Rate Limits

If you exceed your rate limit, the API will return a 429 Too Many Requests response. It's important to implement proper error handling and retry logic in your application to handle rate limiting gracefully.

Error Handling

When an error occurs, the API returns an appropriate HTTP status code along with a JSON response containing error details:

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or missing",
    "status": 401
  }
}

Common Error Codes

Status Code	Error Code	Description
400	invalid_request	The request was malformed or invalid
401	invalid_api_key	The API key is invalid or missing
403	forbidden	You don't have permission to perform this action
404	not_found	The requested resource was not found
415	unsupported_media_type	The uploaded file format is not supported
422	unprocessable_entity	The image could not be processed
429	rate_limit_exceeded	You've exceeded the rate limit for your plan
500	server_error	An unexpected error occurred on our servers

Best Practices for Error Handling

Always check the HTTP status code and success field in the response.
Implement proper retry logic with exponential backoff for rate limiting and server errors.
Log error details for debugging purposes.
Provide meaningful error messages to users of your application.

Remove Background

The background removal endpoints allow you to process images and remove their backgrounds. You can provide images as URLs or upload them directly as files.

POST /remove-background/url

Removes the background from an image provided as a URL.

Request Parameters

Parameter	Type	Description
url Required	string	The URL of the image to process. Must be publicly accessible.
output_format Optional	string	The desired output format. Supported values: `png` (default), `jpg`, `webp`.
output_size Optional	string	The desired output size. Supported values: `original` (default), `small` (1080px), `medium` (1920px), `large` (2880px).
bg_color Optional	string	Hex color code for background (e.g., "#FF0000" for red). Only applicable when output_format is 'jpg'.
webhook_url Optional	string	A URL to receive a webhook notification when processing is complete.

Example Request

curl -X POST https://api.removai.com/v1/remove-background/url \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/image.jpg",
    "output_format": "png",
    "output_size": "original"
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "img_12345abcde",
    "original_url": "https://example.com/image.jpg",
    "output_url": "https://storage.removai.com/img_12345abcde.png",
    "output_size": "original",
    "output_format": "png",
    "created_at": "2025-04-24T10:30:45Z",
    "status": "completed"
  }
}

POST /remove-background/file

Removes the background from an uploaded image file.

Request Parameters

Parameter	Type	Description
file Required	file	The image file to process. Supported formats: JPG, PNG, WEBP. Max size: 25MB.
output_format Optional	string	The desired output format. Supported values: `png` (default), `jpg`, `webp`.
output_size Optional	string	The desired output size. Supported values: `original` (default), `small` (1080px), `medium` (1920px), `large` (2880px).
bg_color Optional	string	Hex color code for background (e.g., "#FF0000" for red). Only applicable when output_format is 'jpg'.
webhook_url Optional	string	A URL to receive a webhook notification when processing is complete.

Example Request

curl -X POST https://api.removai.com/v1/remove-background/file \
  -H "X-API-Key: your_api_key_here" \
  -F "file=@/path/to/image.jpg" \
  -F "output_format=png" \
  -F "output_size=original"

Example Response

{
  "success": true,
  "data": {
    "id": "img_67890fghij",
    "output_url": "https://storage.removai.com/img_67890fghij.png",
    "output_size": "original",
    "output_format": "png",
    "created_at": "2025-04-24T11:15:30Z",
    "status": "completed"
  }
}

POST /remove-background/batch

Processes multiple images in a single request. Only available on Pro and Enterprise plans.

Request Parameters

Parameter	Type	Description
urls Optional	array	Array of image URLs to process. Either this or 'files' must be provided.
files Optional	array of files	Array of image files to process. Either this or 'urls' must be provided.
output_format Optional	string	The desired output format. Supported values: `png` (default), `jpg`, `webp`.
output_size Optional	string	The desired output size. Supported values: `original` (default), `small` (1080px), `medium` (1920px), `large` (2880px).
bg_color Optional	string	Hex color code for background (e.g., "#FF0000" for red). Only applicable when output_format is 'jpg'.
webhook_url Optional	string	A URL to receive a webhook notification when all images are processed.

Example Request (with URLs)

curl -X POST https://api.removai.com/v1/remove-background/batch \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg",
      "https://example.com/image3.jpg"
    ],
    "output_format": "png",
    "output_size": "medium"
  }'

Example Response

{
  "success": true,
  "data": {
    "batch_id": "batch_123456abcdef",
    "total_images": 3,
    "status": "processing",
    "created_at": "2025-04-24T12:45:20Z",
    "images": [
      {
        "id": "img_abcdef123456",
        "original_url": "https://example.com/image1.jpg",
        "status": "processing"
      },
      {
        "id": "img_bcdefg234567",
        "original_url": "https://example.com/image2.jpg",
        "status": "processing"
      },
      {
        "id": "img_cdefgh345678",
        "original_url": "https://example.com/image3.jpg",
        "status": "processing"
      }
    ]
  }
}

API Documentation

Getting Started

API Reference

Resources

Introduction

Base URL

Request Format

Response Format

Getting Your API Key

Authentication

API Key Authentication

Example Request with Authentication

Security Best Practices

Rate Limits

Rate Limit Headers

Exceeding Rate Limits

Error Handling

Common Error Codes

Best Practices for Error Handling

Remove Background

Request Parameters

Example Request

Example Response

Request Parameters

Example Request

Example Response

Request Parameters

Example Request (with URLs)

Example Response

Try It Out: Remove Background from URL