NewConnect Claude, Gemini, ChatGPT, and other AI agents to API Ninjas via our MCP server →

Remove Background API

The Remove Background API cuts the subject out of a photo: people, products, animals, cars and other objects. Send an image, as an upload or a link, and get back the subject on a transparent background as a PNG or WebP, or on a color you choose.

Fine detail such as hair, fur and thin edges is kept, and the old background's color is removed from semi-transparent edges, so the cut-out looks natural on any new background. Results keep the photo's full resolution.

Use it for e-commerce product photos, marketplace listings, profile pictures, ID photos, stickers and design tools. Set crop=true to trim the result to the subject, or output=mask to get a mask for your own editing.

Each image counts as 1 API call, up to your plan's monthly background removals: Free 30 (low-resolution previews), Developer 5,000, Business 20,000, Professional 50,000. Your dashboard shows how many you've used this month. See pricing.

More image APIs: the Object Detection API finds and labels the objects in an image, the Face Detect API finds faces, and the Image to Text API reads the text in an image.

Available endpoint:

At a Glance

InputJPEG, PNG or WebP: upload, raw body, or image_url (up to 25 megapixels)
OutputPNG or WebP with transparency, or JPG, as base64 in JSON or as an image file
ResolutionFull size (Free plan: previews up to 0.25 megapixels)
Plan usage1 API call per image
Background removals per monthFree 30, Developer 5,000, Business 20,000, Professional 50,000

Example

Sample photo: a man standing outdoors
Photo
The same photo with the background removed
Result (transparent background)

https://api.api-ninjas.com/v1/removebackground

Removes the background from a photo and returns the subject on a transparent background, or on a color you choose. Returns the image as base64 in JSON, or as an image file.

Parameters

Send the photo as an image upload (multipart form data), as the raw request body, or as an image_url link. The other parameters are query parameters.

  • image  required, unless image_url is set

    The photo, a JPEG, PNG or WebP file up to 4 MB, as a multipart form field named image. You can also send the file as the raw request body with its Content-Type, e.g. image/jpeg.

  • image_url  optional

    A public http or https link to the image, instead of uploading it. Up to 20 MB (4 MB on the Free plan).

  • format  optional

    File format of the result: png (default), webp or jpg. PNG and WebP keep the transparent background, and WebP files are several times smaller. JPG has no transparency, so the background becomes bg_color, or white.

  • bg_color  optional

    Fill the background with this color instead of making it transparent: a hex color code without the #, e.g. ffffff for white or f2f2f2 for light gray.

  • crop  optional

    Set to true to trim the result to the subject, with no empty margins. By default the result is the same size as the photo.

  • output  optional

    image (default) returns the cut-out. mask returns a grayscale mask the size of the photo instead: white for the subject, black for the background, and gray for semi-transparent edges such as hair.

Headers

  • X-Api-Key  required

    API Key associated with your account.

  • Accept  optional

    image/png, image/webp, image/jpeg or image/* returns the image file itself instead of JSON.

  • Content-Type  optional

    The image type, e.g. image/jpeg or image/png, when the request body is the image itself. Multipart uploads set their own content type.

Response

The /v1/removebackground endpoint returns a JSON object with the following fields, or an error if the request is unsuccessful (see errors).

  • image

    The result image, base64-encoded.

  • content_type

    image/png, image/webp or image/jpeg.

  • width

    Width of the result in pixels: the photo's width, unless crop=true or the result is a preview.

  • height

    Height of the result in pixels.

  • foreground_box

    Where the subject is in the result, in pixels: left, top, width and height. Use it to center or place the subject.

  • preview

    true when the result is a low-resolution preview (Free plan).

  • image_url

    For results over about 4.4 MB (for example large PNGs), a link to download the result, valid for 1 hour, instead of image. expires_in (seconds) and size_bytes come with it.

With an image Accept header, the response body is the image file itself, and the same details come as the X-Foreground-Left, X-Foreground-Top, X-Foreground-Width, X-Foreground-Height and X-Preview headers. Results over about 4.4 MB are always JSON with image_url.

Limits

  • JPEG, PNG or WebP images up to 25 megapixels, with each side at least 16 pixels.
  • Uploads up to 4 MB; images from image_url up to 20 MB (4 MB on the Free plan).
  • Results keep the photo's full resolution. Free plan results are previews of up to 0.25 megapixels, e.g. 612 × 408.
  • One image per request. Most photos take 3 to 8 seconds, so set your HTTP client's timeout to 30 seconds or more.

Background removals

Each image counts as 1 API call. Plans also include a monthly number of background removals: Free 30, Developer 5,000, Business 20,000 and Professional 50,000. The count resets on the 1st of each month (UTC), and requests that fail are not counted. Your dashboard shows how many you've used this month, and Professional and Enterprise plans can also read the count from the Analytics API.

Live Demo

Live demo · no API key required
Form data and query parameters
image
Selected file
Using the sample photo until you choose a file.
format
bg_color

Get a free API key to get started — no credit card required.

Headers
X-Api-KeyLog in or sign up to get your API key
POST
https://api.api-ninjas.com/v1/removebackground?format=webp
Sample response
The photo with its background removed

Download the result (800 × 999 px, subject 753 × 953 at 33, 46)

{
"image": "UklGRo4JAgBXRUJQVlA4WAoAAAAQAAAAHwMA5gMAQUxQSPI9...",
"content_type": "image/webp",
"width": 800,
"height": 999,
"foreground_box": {
"left": 33,
"top": 46,
"width": 753,
"height": 953
},
"preview": false
}

No API key is needed to try it. Without a key, the demo returns low-resolution previews, as on the Free plan.

Code Examples

# Remove the background and save the result as a WebP image with transparency. # (Results over about 4.4 MB come back as JSON with a download link in image_url.) curl -X POST "https://api.api-ninjas.com/v1/removebackground?format=webp" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: image/webp" \ -F "image=@photo.jpg" \ --output photo-no-bg.webp

Errors

An invalid request returns HTTP 400 with a JSON body holding a readable error message. If too many images are being processed at once, the API returns HTTP 503: retry after a few seconds. Requests that fail are not counted. Authentication and quota errors use the standard format described in error codes.

CauseExample error
No image in the requestMissing image. Send the file in a form field named image, or pass image_url.
A file that is not a JPEG, PNG or WebP imageUnsupported image format. Send a JPEG, PNG or WebP file.
An upload over 4 MBImage is larger than 4 MB.
An image over 25 megapixelsImage is too large. The maximum is 25 megapixels.
An image under 16 pixels on a sideImage is too small. Each side must be at least 16 pixels.
No subject found, e.g. a blank wallNo foreground subject was found in the image.
An image_url on a private networkimage_url must point to a public internet address.
An image_url that could not be downloadedCould not download image_url (HTTP 404).
A format other than png, webp or jpgformat must be png, webp or jpg.
A bg_color that is not a hex colorbg_color must be a hex color such as ffffff or 000000.
An output other than image or maskoutput must be image or mask.
A crop other than true or falsecrop must be true or false.
All of this month's background removals usedYour Developer plan includes 5,000 background removals a month and they have all been used. The count resets on the 1st of the month (UTC). Upgrade at https://api-ninjas.com/pricing for more.
Free plan: all 30 background removals usedThe Free plan includes 30 background removals a month, at preview size. Upgrade at https://api-ninjas.com/pricing for more images and full resolution.

Frequently Asked Questions

  • Yes, but you must have a premium subscription. Commercial use of the Remove Background API is not permitted on the free tier. See our pricing page to choose a plan that fits your needs.
  • Sign up for a free account to instantly get your API key, then pass it in the X-Api-Key header on every request. The documentation above includes ready-to-run examples in cURL, Python, JavaScript, Node.js, and more.
  • Your API requests will simply be denied once you hit your monthly quota — you will never be charged more than the plan you signed up for. To increase your quota, you can upgrade your plan any time on our pricing page.
  • The API responds with a standard HTTP status code and a JSON error message describing the problem. See our error codes reference for the full list of codes and how to resolve each one, or contact support if you need help.
  • POST the photo to /v1/removebackground as a multipart upload named image, e.g. curl -X POST "https://api.api-ninjas.com/v1/removebackground?format=webp" -H "X-Api-Key: YOUR_API_KEY" -H "Accept: image/webp" -F "image=@photo.jpg" --output photo-no-bg.webp. Without the Accept header the response is JSON with the image base64-encoded in image. A photo that is already online can be passed as image_url instead.
  • png (the default) and webp keep the transparent background; WebP files are several times smaller. jpg has no transparency, so the background is filled with bg_color, or white. Set bg_color (e.g. ffffff) with any format to put the subject on a solid color, crop=true to trim the result to the subject, and output=mask for a grayscale mask instead of the cut-out.
  • Yes. It cuts out people, products, animals, cars and other objects, and keeps fine detail such as hair and fur as semi-transparent edges. The old background's color is removed from those edges, so the cut-out looks natural on a new background. Results keep the photo's full resolution, up to 25 megapixels.
  • Each image counts as 1 API call. Plans also include a monthly number of background removals: Free 30, Developer 5,000, Business 20,000 and Professional 50,000. The count resets on the 1st of each month (UTC), requests that fail are not counted, and your dashboard shows how many you've used this month (Professional and Enterprise plans can also read it from the Analytics API). See pricing.
  • Yes: the Free plan includes 30 background removals a month, as low-resolution previews of up to 0.25 megapixels (for example 612 × 408), marked with preview: true. Paid plans return the full resolution. See pricing.

Explore API integration use cases for recommended APIs and workflow examples.