AI Background Removal API

Remove the background from any photo with a single API call. Send an image, and get back a cutout with a transparent background, a solid color, or a new background image.

The API is a drop-in replacement for the remove.bg API. It uses the same endpoints, parameters, responses and error codes, so existing remove.bg integrations, plugins and SDKs work by changing two things:

the base URL, from https://api.remove.bg to https://remove-bg-di.shortpixel.com
the API key, from your remove.bg key to your ShortPixel API key

Base URL: https://remove-bg-di.shortpixel.com/v1.0

Authentication #

Send your ShortPixel API key in the X-Api-Key header of every request. You can find the key in your ShortPixel account, under API Keys (see Where is my API key?).

X-Api-Key: YOUR_SHORTPIXEL_API_KEY

Background removal uses credits from your ShortPixel account. The number of credits charged for each call is returned in the X-Credits-Charged response header.

Keep the key on your server. Never embed it in browser or mobile app code.

Remove a background: POST /v1.0/removebg #

Send the image in exactly one of these ways:

image_file: upload the file (multipart/form-data)
image_file_b64: send the file as a base64-encoded string
image_url: send a public URL, and our servers download the image

The request body can be multipart/form-data, application/x-www-form-urlencoded or application/json. File uploads (image_file and bg_image_file) need multipart/form-data.

Supported input: JPG, PNG and WebP images, up to 22 MB and up to 50 megapixels.

Parameters

Parameter	Values	Default	Notes
image_file	file		Source image file. Use only one image source
image_file_b64	string		Source image as a base64-encoded string
image_url	string		Public URL of the source image
size	preview, full, 50MP, auto	preview	Output resolution. See Output sizes below
format	auto, png, jpg, webp, zip	auto	auto returns PNG when the result has transparent areas and JPG otherwise. png and webp keep transparency, jpg has none. zip returns a color image plus an alpha mask (see below)
type	auto, person, product, animal, car, graphic, transportation	auto	Foreground type. auto detects it
type_level	none, 1, 2, latest	1	Detail level of the detected type returned in X-Type. none leaves X-Type out
channels	rgba, alpha	rgba	rgba returns the finished image. alpha returns only the black-and-white mask
bg_color	hex code or color name		Solid background, for example 81d4fa, fff or green. 4- and 8-digit hex codes add transparency, for example 81d4fa77
bg_image_url	string		URL of a background image. It is centered and resized to fill the canvas
bg_image_file	file		Background image file. It is centered and resized to fill the canvas

Use only one background option: bg_color, bg_image_url or bg_image_file.

Output sizes

size	Output resolution
preview (default)	Up to 0.25 megapixels, for example 625×400
full	Original resolution, up to 25 megapixels
50MP	Original resolution, up to 50 megapixels
auto	Highest available resolution, up to 25 megapixels

For compatibility, size also accepts the older remove.bg values: small and regular (same as preview), medium (up to 1.5 megapixels), hd (up to 4 megapixels) and 4k (same as full).

Response #

A successful call returns HTTP 200 with the result image in the response body. The Content-Type header tells you the format (image/png, image/jpeg, image/webp or application/zip).

Response header	Description
X-Credits-Charged	Credits charged for this call
X-Width	Width of the result image, in pixels
X-Height	Height of the result image, in pixels
X-Type	Foreground type. Not sent when type_level is none

JSON response. Send the header Accept: application/json to get the result as base64 inside a JSON object instead of a binary file:

{
  "data": {
    "result_b64": "iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

ZIP format. With format=zip you get an archive with two files: color.jpg (the colors of the image) and alpha.png (the mask, where white is the foreground). To combine the two files into a transparent PNG, for example with ImageMagick:

convert color.jpg alpha.png -compose CopyOpacity -composite no-bg.png

Check your credits: GET /v1.0/account #

Returns the credit balance of the account that owns the API key.

curl -H "X-Api-Key: YOUR_SHORTPIXEL_API_KEY" https://remove-bg-di.shortpixel.com/v1.0/account

{
  "data": {
    "attributes": {
      "credits": {
        "subscription": 10000,
        "payg": 0,
        "enterprise": 0,
        "total": 10000
      },
      "api": {
        "free_calls": 0,
        "sizes": "all"
      }
    }
  }
}

To keep track of your balance, call this endpoint once, then subtract the X-Credits-Charged value of each call.

Errors #

Errors return a JSON body with an errors array. Each error has a title, and most also have a code and a detail:

{
  "errors": [
    {
      "title": "No image given",
      "code": "missing_source",
      "detail": "Please provide the source image in the image_url, image_file or image_file_b64 parameter."
    }
  ]
}

HTTP	Meaning
400	Invalid parameters, or the image could not be processed
402	Not enough credits
403	Missing or invalid API key
405	Wrong HTTP method (for example GET instead of POST on /removebg)
429	Too many requests. Wait and try again. If the response includes a Retry-After header, wait that many seconds
5xx	Temporary server error. Retry with an increasing delay

Common 400 error codes

code	Cause
missing_source	No image_file, image_file_b64 or image_url was sent
multiple_sources	More than one image source was sent
invalid_image_url	image_url is not a valid URL
failed_image_download	The image could not be downloaded from image_url
invalid_file_type	The file is not a JPG, PNG or WebP image
file_too_large	The file is larger than 22 MB
resolution_too_high	The image is larger than 50 megapixels
invalid_size, invalid_format, invalid_channels, invalid_bg_color	A parameter has a value that is not allowed
multiple_bg_sources	More than one of bg_color, bg_image_url and bg_image_file was sent
failed_bg_download	The background image could not be downloaded from bg_image_url

Code examples #

The examples read the API key from the SHORTPIXEL_API_KEY environment variable and save the result as no-bg.png.

curl: upload a file

curl -H "X-Api-Key: $SHORTPIXEL_API_KEY" \
  -F "image_file=@/path/to/photo.jpg" \
  -F "size=auto" \
  -f https://remove-bg-di.shortpixel.com/v1.0/removebg -o no-bg.png

curl: image from a URL

curl -H "X-Api-Key: $SHORTPIXEL_API_KEY" \
  -F "image_url=https://example.com/photo.jpg" \
  -F "size=auto" \
  -f https://remove-bg-di.shortpixel.com/v1.0/removebg -o no-bg.png

curl: JSON request and JSON response

curl -H "X-Api-Key: $SHORTPIXEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"image_url": "https://example.com/photo.jpg", "size": "preview"}' \
  https://remove-bg-di.shortpixel.com/v1.0/removebg

PHP

<?php
$ch = curl_init('https://remove-bg-di.shortpixel.com/v1.0/removebg');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('SHORTPIXEL_API_KEY')],
    CURLOPT_POSTFIELDS => [
        'image_file' => new CURLFile('photo.jpg'),
        'size' => 'auto',
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status !== 200) {
    $error = json_decode($body, true);
    throw new RuntimeException($error['errors'][0]['title'] ?? "HTTP $status");
}
file_put_contents('no-bg.png', $body);

JavaScript (Node 18+)

import { readFile, writeFile } from 'node:fs/promises';

const form = new FormData();
form.append('image_file', new Blob([await readFile('photo.jpg')]), 'photo.jpg');
form.append('size', 'auto');

const res = await fetch('https://remove-bg-di.shortpixel.com/v1.0/removebg', {
  method: 'POST',
  headers: { 'X-Api-Key': process.env.SHORTPIXEL_API_KEY },
  body: form,
});
if (!res.ok) {
  const { errors } = await res.json();
  throw new Error(errors[0].title);
}
await writeFile('no-bg.png', Buffer.from(await res.arrayBuffer()));

Python

import os
import requests

with open("photo.jpg", "rb") as image:
    response = requests.post(
        "https://remove-bg-di.shortpixel.com/v1.0/removebg",
        files={"image_file": image},
        data={"size": "auto"},
        headers={"X-Api-Key": os.environ["SHORTPIXEL_API_KEY"]},
        timeout=120,
    )

if response.status_code == 200:
    with open("no-bg.png", "wb") as out:
        out.write(response.content)
else:
    print("Error:", response.status_code, response.json()["errors"][0]["title"])

Switching from remove.bg #

Replace the base URL and the API key, and keep everything else:

# Before
curl -H "X-Api-Key: YOUR_REMOVE_BG_KEY" -F "image_file=@photo.jpg" \
  https://api.remove.bg/v1.0/removebg -o no-bg.png

# After
curl -H "X-Api-Key: YOUR_SHORTPIXEL_API_KEY" -F "image_file=@photo.jpg" \
  https://remove-bg-di.shortpixel.com/v1.0/removebg -o no-bg.png

If a plugin or SDK lets you set the API URL, enter https://remove-bg-di.shortpixel.com/v1.0 as the URL and your ShortPixel API key as the key.