{"id":3003,"date":"2026-11-13T12:38:40","date_gmt":"2026-11-13T12:38:40","guid":{"rendered":"https:\/\/kb.shortpixel.com\/?post_type=docs&#038;p=3003"},"modified":"2026-11-13T12:38:42","modified_gmt":"2026-11-13T12:38:42","password":"","slug":"ai-background-removal-api","status":"publish","type":"docs","link":"https:\/\/kb.shortpixel.com\/knowledge-base\/article\/ai-background-removal-api\/","title":{"rendered":"AI Background Removal API"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">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.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">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:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>the base URL, from https:\/\/api.remove.bg to https:\/\/remove-bg-di.shortpixel.com<\/li>\n\n\n\n<li>the API key, from your remove.bg key to your ShortPixel API key<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">Base URL: https:\/\/remove-bg-di.shortpixel.com\/v1.0<\/p>\n\n\n\n<h1 class=\"wp-block-heading\"><strong>Authentication<\/strong><\/h1>\n\n\n\n<p class=\"wp-block-paragraph\">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 <a href=\"https:\/\/kb.shortpixel.com\/knowledge-base\/article\/where-is-my-api-key\/\">Where is my API key?<\/a>).<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>X-Api-Key: YOUR_SHORTPIXEL_API_KEY<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">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.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Keep the key on your server. Never embed it in browser or mobile app code.<\/p>\n\n\n\n<h1 class=\"wp-block-heading\"><strong>Remove a background: POST \/v1.0\/removebg<\/strong><\/h1>\n\n\n\n<p class=\"wp-block-paragraph\">Send the image in exactly one of these ways:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>image_file<\/strong>: upload the file (multipart\/form-data)<\/li>\n\n\n\n<li><strong>image_file_b64<\/strong>: send the file as a base64-encoded string<\/li>\n\n\n\n<li><strong>image_url<\/strong>: send a public URL, and our servers download the image<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">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.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Supported input: JPG, PNG and WebP images, up to 22 MB and up to 50 megapixels.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Parameters<\/strong><\/p>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-fixed-layout\"><thead><tr><th><strong>Parameter<\/strong><\/th><th><strong>Values<\/strong><\/th><th><strong>Default<\/strong><\/th><th><strong>Notes<\/strong><\/th><\/tr><\/thead><tbody><tr><td>image_file<\/td><td>file<\/td><td><\/td><td>Source image file. Use only one image source<\/td><\/tr><tr><td>image_file_b64<\/td><td>string<\/td><td><\/td><td>Source image as a base64-encoded string<\/td><\/tr><tr><td>image_url<\/td><td>string<\/td><td><\/td><td>Public URL of the source image<\/td><\/tr><tr><td>size<\/td><td>preview, full, 50MP, auto<\/td><td>preview<\/td><td>Output resolution. See Output sizes below<\/td><\/tr><tr><td>format<\/td><td>auto, png, jpg, webp, zip<\/td><td>auto<\/td><td>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)<\/td><\/tr><tr><td>type<\/td><td>auto, person, product, animal, car, graphic, transportation<\/td><td>auto<\/td><td>Foreground type. auto detects it<\/td><\/tr><tr><td>type_level<\/td><td>none, 1, 2, latest<\/td><td>1<\/td><td>Detail level of the detected type returned in X-Type. none leaves X-Type out<\/td><\/tr><tr><td>channels<\/td><td>rgba, alpha<\/td><td>rgba<\/td><td>rgba returns the finished image. alpha returns only the black-and-white mask<\/td><\/tr><tr><td>bg_color<\/td><td>hex code or color name<\/td><td><\/td><td>Solid background, for example 81d4fa, fff or green. 4- and 8-digit hex codes add transparency, for example 81d4fa77<\/td><\/tr><tr><td>bg_image_url<\/td><td>string<\/td><td><\/td><td>URL of a background image. It is centered and resized to fill the canvas<\/td><\/tr><tr><td>bg_image_file<\/td><td>file<\/td><td><\/td><td>Background image file. It is centered and resized to fill the canvas<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">Use only one background option: bg_color, bg_image_url or bg_image_file.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Output sizes<\/strong><\/p>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-fixed-layout\"><thead><tr><th><strong>size<\/strong><\/th><th><strong>Output resolution<\/strong><\/th><\/tr><\/thead><tbody><tr><td>preview (default)<\/td><td>Up to 0.25 megapixels, for example 625\u00d7400<\/td><\/tr><tr><td>full<\/td><td>Original resolution, up to 25 megapixels<\/td><\/tr><tr><td>50MP<\/td><td>Original resolution, up to 50 megapixels<\/td><\/tr><tr><td>auto<\/td><td>Highest available resolution, up to 25 megapixels<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">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).<\/p>\n\n\n\n<h1 class=\"wp-block-heading\"><strong>Response<\/strong><\/h1>\n\n\n\n<p class=\"wp-block-paragraph\">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).<\/p>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-fixed-layout\"><thead><tr><th><strong>Response header<\/strong><\/th><th><strong>Description<\/strong><\/th><\/tr><\/thead><tbody><tr><td>X-Credits-Charged<\/td><td>Credits charged for this call<\/td><\/tr><tr><td>X-Width<\/td><td>Width of the result image, in pixels<\/td><\/tr><tr><td>X-Height<\/td><td>Height of the result image, in pixels<\/td><\/tr><tr><td>X-Type<\/td><td>Foreground type. Not sent when type_level is none<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>JSON response.<\/strong> Send the header Accept: application\/json to get the result as base64 inside a JSON object instead of a binary file:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>{\n  \"data\": {\n    \"result_b64\": \"iVBORw0KGgoAAAANSUhEUgAA...\"\n  }\n}<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>ZIP format.<\/strong> 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:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>convert color.jpg alpha.png -compose CopyOpacity -composite no-bg.png<\/code><\/pre>\n\n\n\n<h1 class=\"wp-block-heading\"><strong>Check your credits: GET \/v1.0\/account<\/strong><\/h1>\n\n\n\n<p class=\"wp-block-paragraph\">Returns the credit balance of the account that owns the API key.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>curl -H \"X-Api-Key: YOUR_SHORTPIXEL_API_KEY\" https:\/\/remove-bg-di.shortpixel.com\/v1.0\/account<\/code><\/pre>\n\n\n\n<pre class=\"wp-block-code\"><code>{\n  \"data\": {\n    \"attributes\": {\n      \"credits\": {\n        \"subscription\": 10000,\n        \"payg\": 0,\n        \"enterprise\": 0,\n        \"total\": 10000\n      },\n      \"api\": {\n        \"free_calls\": 0,\n        \"sizes\": \"all\"\n      }\n    }\n  }\n}<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">To keep track of your balance, call this endpoint once, then subtract the X-Credits-Charged value of each call.<\/p>\n\n\n\n<h1 class=\"wp-block-heading\"><strong>Errors<\/strong><\/h1>\n\n\n\n<p class=\"wp-block-paragraph\">Errors return a JSON body with an errors array. Each error has a title, and most also have a code and a detail:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>{\n  \"errors\": &#91;\n    {\n      \"title\": \"No image given\",\n      \"code\": \"missing_source\",\n      \"detail\": \"Please provide the source image in the image_url, image_file or image_file_b64 parameter.\"\n    }\n  ]\n}<\/code><\/pre>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-fixed-layout\"><thead><tr><th><strong>HTTP<\/strong><\/th><th><strong>Meaning<\/strong><\/th><\/tr><\/thead><tbody><tr><td>400<\/td><td>Invalid parameters, or the image could not be processed<\/td><\/tr><tr><td>402<\/td><td>Not enough credits<\/td><\/tr><tr><td>403<\/td><td>Missing or invalid API key<\/td><\/tr><tr><td>405<\/td><td>Wrong HTTP method (for example GET instead of POST on \/removebg)<\/td><\/tr><tr><td>429<\/td><td>Too many requests. Wait and try again. If the response includes a Retry-After header, wait that many seconds<\/td><\/tr><tr><td>5xx<\/td><td>Temporary server error. Retry with an increasing delay<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Common 400 error codes<\/strong><\/p>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-fixed-layout\"><thead><tr><th><strong>code<\/strong><\/th><th><strong>Cause<\/strong><\/th><\/tr><\/thead><tbody><tr><td>missing_source<\/td><td>No image_file, image_file_b64 or image_url was sent<\/td><\/tr><tr><td>multiple_sources<\/td><td>More than one image source was sent<\/td><\/tr><tr><td>invalid_image_url<\/td><td>image_url is not a valid URL<\/td><\/tr><tr><td>failed_image_download<\/td><td>The image could not be downloaded from image_url<\/td><\/tr><tr><td>invalid_file_type<\/td><td>The file is not a JPG, PNG or WebP image<\/td><\/tr><tr><td>file_too_large<\/td><td>The file is larger than 22 MB<\/td><\/tr><tr><td>resolution_too_high<\/td><td>The image is larger than 50 megapixels<\/td><\/tr><tr><td>invalid_size, invalid_format, invalid_channels, invalid_bg_color<\/td><td>A parameter has a value that is not allowed<\/td><\/tr><tr><td>multiple_bg_sources<\/td><td>More than one of bg_color, bg_image_url and bg_image_file was sent<\/td><\/tr><tr><td>failed_bg_download<\/td><td>The background image could not be downloaded from bg_image_url<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<h1 class=\"wp-block-heading\"><strong>Code examples<\/strong><\/h1>\n\n\n\n<p class=\"wp-block-paragraph\">The examples read the API key from the SHORTPIXEL_API_KEY environment variable and save the result as no-bg.png.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>curl: upload a file<\/strong><\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>curl -H \"X-Api-Key: $SHORTPIXEL_API_KEY\" \\\n  -F \"image_file=@\/path\/to\/photo.jpg\" \\\n  -F \"size=auto\" \\\n  -f https:\/\/remove-bg-di.shortpixel.com\/v1.0\/removebg -o no-bg.png<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>curl: image from a URL<\/strong><\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>curl -H \"X-Api-Key: $SHORTPIXEL_API_KEY\" \\\n  -F \"image_url=https:\/\/example.com\/photo.jpg\" \\\n  -F \"size=auto\" \\\n  -f https:\/\/remove-bg-di.shortpixel.com\/v1.0\/removebg -o no-bg.png<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>curl: JSON request and JSON response<\/strong><\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>curl -H \"X-Api-Key: $SHORTPIXEL_API_KEY\" \\\n  -H \"Content-Type: application\/json\" \\\n  -H \"Accept: application\/json\" \\\n  -d '{\"image_url\": \"https:\/\/example.com\/photo.jpg\", \"size\": \"preview\"}' \\\n  https:\/\/remove-bg-di.shortpixel.com\/v1.0\/removebg<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>PHP<\/strong><\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>&lt;?php\n$ch = curl_init('https:\/\/remove-bg-di.shortpixel.com\/v1.0\/removebg');\ncurl_setopt_array($ch, &#91;\n    CURLOPT_POST =&gt; true,\n    CURLOPT_RETURNTRANSFER =&gt; true,\n    CURLOPT_HTTPHEADER =&gt; &#91;'X-Api-Key: ' . getenv('SHORTPIXEL_API_KEY')],\n    CURLOPT_POSTFIELDS =&gt; &#91;\n        'image_file' =&gt; new CURLFile('photo.jpg'),\n        'size' =&gt; 'auto',\n    ],\n]);\n$body = curl_exec($ch);\n$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);\ncurl_close($ch);\n\nif ($status !== 200) {\n    $error = json_decode($body, true);\n    throw new RuntimeException($error&#91;'errors']&#91;0]&#91;'title'] ?? \"HTTP $status\");\n}\nfile_put_contents('no-bg.png', $body);<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>JavaScript (Node 18+)<\/strong><\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>import { readFile, writeFile } from 'node:fs\/promises';\n\nconst form = new FormData();\nform.append('image_file', new Blob(&#91;await readFile('photo.jpg')]), 'photo.jpg');\nform.append('size', 'auto');\n\nconst res = await fetch('https:\/\/remove-bg-di.shortpixel.com\/v1.0\/removebg', {\n  method: 'POST',\n  headers: { 'X-Api-Key': process.env.SHORTPIXEL_API_KEY },\n  body: form,\n});\nif (!res.ok) {\n  const { errors } = await res.json();\n  throw new Error(errors&#91;0].title);\n}\nawait writeFile('no-bg.png', Buffer.from(await res.arrayBuffer()));<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Python<\/strong><\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>import os\nimport requests\n\nwith open(\"photo.jpg\", \"rb\") as image:\n    response = requests.post(\n        \"https:\/\/remove-bg-di.shortpixel.com\/v1.0\/removebg\",\n        files={\"image_file\": image},\n        data={\"size\": \"auto\"},\n        headers={\"X-Api-Key\": os.environ&#91;\"SHORTPIXEL_API_KEY\"]},\n        timeout=120,\n    )\n\nif response.status_code == 200:\n    with open(\"no-bg.png\", \"wb\") as out:\n        out.write(response.content)\nelse:\n    print(\"Error:\", response.status_code, response.json()&#91;\"errors\"]&#91;0]&#91;\"title\"])<\/code><\/pre>\n\n\n\n<h1 class=\"wp-block-heading\"><strong>Switching from remove.bg<\/strong><\/h1>\n\n\n\n<p class=\"wp-block-paragraph\">Replace the base URL and the API key, and keep everything else:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code># Before\ncurl -H \"X-Api-Key: YOUR_REMOVE_BG_KEY\" -F \"image_file=@photo.jpg\" \\\n  https:\/\/api.remove.bg\/v1.0\/removebg -o no-bg.png\n\n# After\ncurl -H \"X-Api-Key: YOUR_SHORTPIXEL_API_KEY\" -F \"image_file=@photo.jpg\" \\\n  https:\/\/remove-bg-di.shortpixel.com\/v1.0\/removebg -o no-bg.png<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">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.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>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, [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","template":"","meta":{"footnotes":""},"doc_category":[61],"glossaries":[],"doc_tag":[],"class_list":["post-3003","docs","type-docs","status-publish","hentry","doc_category-tools-developer-api"],"blocksy_meta":[],"year_month":"2026-11","word_count":1313,"total_views":"2","reactions":{"happy":"0","normal":"0","sad":"0"},"author_info":{"name":"admin","author_nicename":"admin_mdli53m5","author_url":"https:\/\/kb.shortpixel.com\/author\/admin_mdli53m5\/"},"doc_category_info":[{"term_name":"Tools &amp; Developer API","term_url":"https:\/\/kb.shortpixel.com\/knowledge-base\/category\/tools-developer-api\/"}],"doc_tag_info":[],"knowledge_base_info":[],"knowledge_base_slug":[],"_links":{"self":[{"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/docs\/3003","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/docs"}],"about":[{"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/types\/docs"}],"author":[{"embeddable":true,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/comments?post=3003"}],"version-history":[{"count":1,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/docs\/3003\/revisions"}],"predecessor-version":[{"id":3004,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/docs\/3003\/revisions\/3004"}],"wp:attachment":[{"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/media?parent=3003"}],"wp:term":[{"taxonomy":"doc_category","embeddable":true,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/doc_category?post=3003"},{"taxonomy":"glossaries","embeddable":true,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/glossaries?post=3003"},{"taxonomy":"doc_tag","embeddable":true,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/doc_tag?post=3003"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}