remove.bg API migration guide
Change the base URL. Keep the header, the path, and the parameter names.
What changes on Dec 1, 2026
remove.bg closes its standalone site on Dec 1, 2026. ZeroBG accepts the same call at POST https://zerobg.ai/v1.0/removebg. Send the key in X-Api-Key. Parameter names stay the same.
Account balance is GET https://zerobg.ai/v1.0/account. The full parameter list is the API reference.
Three steps
- Create a key. Any account with credits can create one. A Pro subscription is not required.
- Replace https://api.remove.bg with https://zerobg.ai. Leave the path as /v1.0/removebg, so the call is POST https://zerobg.ai/v1.0/removebg.
- Send the ZeroBG key in the X-Api-Key header. X-API-Key is the same header.
Before (remove.bg)
curl -X POST \ -H "X-Api-Key: YOUR_REMOVEBG_KEY" \ -F "image_file=@/path/to/image.jpg" \ -F "size=auto" \ https://api.remove.bg/v1.0/removebg --output result.png
After (ZeroBG)
curl -X POST \ -H "X-Api-Key: YOUR_ZEROBG_KEY" \ -F "image_file=@/path/to/image.jpg" \ -F "size=auto" \ https://zerobg.ai/v1.0/removebg --output result.png
Compatibility
Bodies may be multipart/form-data, application/json, or application/x-www-form-urlencoded.
| Parameter | Behavior |
|---|---|
| image_file | JPG, PNG, or WebP upload, up to 25MB. |
| image_url | Public http(s) URL. Private and link-local addresses are rejected. |
| image_file_b64 | Base64, with or without a data-URL prefix. |
| size | preview (default), small, regular, medium, hd, full, 4k, auto, 50MP. preview is 0.25MP, medium 1.5MP, hd 4MP. full, 4k, auto, and 50MP keep the model output. |
| format | png, jpg, jpeg, webp, zip, or auto. auto is png, or jpg when a solid background is set. zip is color.jpg plus alpha.png. |
| bg_color | Hex (#fff, #ffffff, #ffffffff) or a common color name such as white. |
| bg_image_url / bg_image_file | One background image. Use only one of bg_color, bg_image_url, and bg_image_file. |
| channels | rgba (default) or alpha (the mask only). |
| crop / crop_margin | crop=true trims to the subject. crop_margin takes 1, 2, or 4 px or % values. |
| scale / position | Scale is 10–100% or original. position is original, center, or x% y%. |
| roi | Four px or % values: x1 y1 x2 y2. Only that box can be foreground. |
| type / type_level | Accepted. See the differences below. There is no separate classifier. |
| JSON body | Strings, finite numbers, and booleans. null, objects, and arrays are ignored. crop: true and shadow_opacity: 50 both count. |
Response headers on 200
- X-Credits-Charged: 1
- X-Credits-Remaining: balance after this call
- X-Width, X-Height
- X-Foreground-Top, X-Foreground-Left, X-Foreground-Width, X-Foreground-Height
- X-Type: the type you sent, or other. Omitted when type_level=none
- X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
- Retry-After: on 429
JSON result
The default body is the image. Accept: application/json returns JSON only when every type in that header is application/json. A charset parameter is fine. The axios default application/json, text/plain, */* still returns the image.
{
"data": {
"result_b64": "…",
"foreground_top": 12,
"foreground_left": 40,
"foreground_width": 320,
"foreground_height": 480
}
}GET /v1.0/account
enterprise is always 0, free_calls is always 0, and sizes is always all. total, subscription, and payg are the balance. Subscription credits are spent first.
{
"data": {
"attributes": {
"credits": { "total": 20, "subscription": 0, "payg": 20, "enterprise": 0 },
"api": { "free_calls": 0, "sizes": "all" }
}
}
}Account balance
curl -H "X-Api-Key: YOUR_ZEROBG_KEY" \ https://zerobg.ai/v1.0/account
Different or not applied
- Every successful call uses 1 credit, including size=preview.
- add_shadow, shadow_type, and shadow_opacity do not draw a shadow. Both add_shadow and shadow_type together return 400.
- semitransparency is validated and not applied.
- type is echoed in X-Type. It is not a detection result. type_level=none omits the header.
- Missing or invalid keys return 403 with { "errors": [{ "code", "title" }] }.
- 400 invalid parameters, 402 no credits, 429 rate limit, 500 processing failed (credit refunded).
- No CORS header. Call the API from your server.
By library
PHP mtownsend/remove-bg and the Ruby remove_bg gem take a base URL. The other clients hardcode https://api.remove.bg. Snippets come from those repositories and were not executed against ZeroBG. Zapier, Make, and n8n labels were not clicked in the current UI.
PHP mtownsend/remove-bg
Set $endpoint. account() swaps /removebg for /account on that host. save() and get() read the image bytes. getBase64() sends Accept: application/json and reads data.result_b64, which this endpoint returns. Source checked 2026-11-13. The package header is X-API-Key, the same header as X-Api-Key.
PHP
use Mtownsend\RemoveBg\RemoveBg;
$removebg = new RemoveBg('YOUR_ZEROBG_API_KEY');
$removebg->endpoint = 'https://zerobg.ai/v1.0/removebg';
$removebg->url('https://example.com/photo.jpg')->save('no-bg.png');
$info = $removebg->account(); // GET https://zerobg.ai/v1.0/accountThe Laravel removebg() helper builds a new instance each time, so set endpoint on that instance. config/removebg.php has an api key and no endpoint. The container extend below follows the package service provider and was not run.
Laravel
// AppServiceProvider::register() — follows the package bind, not run here
$this->app->extend('removebg', function ($rb) {
$rb->endpoint = 'https://zerobg.ai/v1.0/removebg';
return $rb;
});Ruby remove_bg
HttpConnection.build takes the base URL. The gem reads X-Type, X-Width, X-Height, X-Credits-Charged, and the rate-limit headers, which this endpoint sends. format=zip returns color.jpg and alpha.png. account_info reads data.attributes.credits, which GET /v1.0/account returns. A boot-time alias of build was not run; construct the client.
Ruby
require "remove_bg"
client = RemoveBg::ApiClient.new(
connection: RemoveBg::HttpConnection.build("https://zerobg.ai")
)
options = RemoveBg::RequestOptions.new(
api_key: ENV.fetch("ZEROBG_API_KEY"),
size: "auto"
)
client.remove_from_file("input.jpg", options).save("output.png")Python removebg (brilam)
API_ENDPOINT is a module global read at call time. Overwrite it after import. A constructor argument for the endpoint exists only in an unmerged pull request, so the published package does not have it. Source read 2026-11-07.
Python removebg
import removebg.removebg as _rb
_rb.API_ENDPOINT = "https://zerobg.ai/v1.0/removebg" # read when the call runs
from removebg import RemoveBg
rmbg = RemoveBg("YOUR_ZEROBG_API_KEY", "error.log")
rmbg.remove_background_from_img_file("photo.jpg")npm remove.bg
Master still sets API_ENDPOINT to https://api.remove.bg/v1.0/removebg, sends Accept: application/json, and reads body.data.result_b64. URL and base64 calls send a JSON body. Booleans such as crop: true and finite numbers are accepted. The JSON body this package reads is implemented. The URL is still private to the module, so the request has to be redirected. Source checked 2026-11-13. The patch below needs the same unirest object the package calls, and it was not executed here. If Node loads a different copy, use the fetch example further down.
npm remove.bg
const unirest = require("unirest");
const post = unirest.post;
unirest.post = (url, ...rest) =>
post(String(url).replace("https://api.remove.bg", "https://zerobg.ai"), ...rest);
const { removeBackgroundFromImageUrl } = require("remove.bg");
const result = await removeBackgroundFromImageUrl({
apiKey: process.env.ZEROBG_API_KEY,
url: "https://example.com/photo.jpg",
size: "auto",
});
// result.base64img comes from data.result_b64@corsair-dev/removebg also hardcodes the URL and reads data.result_b64 (package read 2026-11-07). The JSON response is supported. The URL is not configurable. Use fetch.
Go remove-bg/go
The official module hardcodes the endpoint and is archived. As a library, its HTTPClient can carry a RoundTripper that rewrites the host. That transport was not run. The published CLI cannot be patched; use curl or the HTTP sample. g-lib/removebg exports APIENDPOINT and reads it at request time (source read 2026-11-07).
Go RoundTripper
type zerobgRT struct{ base http.RoundTripper }
func (t zerobgRT) RoundTrip(r *http.Request) (*http.Response, error) {
if r.URL.Host == "api.remove.bg" {
r = r.Clone(r.Context())
r.URL.Host = "zerobg.ai"
r.Host = "zerobg.ai"
}
return t.base.RoundTrip(r)
}
c := client.Client{
Version: "dev",
HTTPClient: http.Client{Transport: zerobgRT{http.DefaultTransport}},
}g-lib/removebg
import "github.com/g-lib/removebg"
removebg.APIENDPOINT = "https://zerobg.ai/v1.0/removebg"
rb := removebg.NewRemoveBG(os.Getenv("ZEROBG_API_KEY"))Go HTTP
body := &bytes.Buffer{}
w := multipart.NewWriter(body)
fw, _ := w.CreateFormFile("image_file", "in.jpg")
f, _ := os.Open("in.jpg")
io.Copy(fw, f)
f.Close()
w.WriteField("size", "auto")
w.Close()
req, _ := http.NewRequest("POST", "https://zerobg.ai/v1.0/removebg", body)
req.Header.Set("X-Api-Key", os.Getenv("ZEROBG_API_KEY"))
req.Header.Set("Content-Type", w.FormDataContentType())
resp, err := http.DefaultClient.Do(req) // 200: resp.Body is the image.NET BAUERGROUP.Shared.Cloud and RemoveBg.Net
Both hardcode the host and accept an HttpClient. BAUERGROUP, checked 2026-11-13, adds Accept: application/json and then calls ReadAsByteArrayAsync for the image. That Accept value now receives JSON, so a host rewrite alone would save the JSON document as the file. The handler below rewrites the host and asks for image/* on POST. Account GET stays on application/json. RemoveBg.Net source from 2026-11-07 sends Accept: image/* and reads bytes; that file was not re-fetched for this page. Neither handler was executed.
DelegatingHandler
public sealed class ZeroBgRedirectHandler : DelegatingHandler
{
protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage req, CancellationToken ct)
{
if (req.RequestUri is { Host: "api.remove.bg" } u)
req.RequestUri = new UriBuilder(u) { Host = "zerobg.ai" }.Uri;
// BAUERGROUP sends Accept: application/json and then reads the body as bytes.
// That Accept value receives JSON here. Ask for the image on the removebg POST.
if (req.Method == HttpMethod.Post)
{
req.Headers.Accept.Clear();
req.Headers.Accept.ParseAdd("image/*");
}
return base.SendAsync(req, ct);
}
}WordPress iTransparent and wc-remove-bg
Both call wp_remote_post with a hardcoded URL (source read 2026-11-07). iTransparent also calls /v1.0/account. A mu-plugin can rewrite any request that starts with https://api.remove.bg/. Put the ZeroBG key in the plugin settings. wc-remove-bg sends a base64 string that may include a data: prefix; that prefix is stripped. This filter was not run on a WordPress site.
mu-plugin
<?php
// wp-content/mu-plugins/zerobg-redirect.php
add_filter('pre_http_request', function ($pre, $args, $url) {
if (strpos($url, 'https://api.remove.bg/') === 0) {
return wp_remote_request(str_replace('https://api.remove.bg', 'https://zerobg.ai', $url), $args);
}
return $pre;
}, 10, 3);Zapier, Make, n8n, Pipedream
The Pipedream remove_bg component posts to a hardcoded URL and sends Accept: application/json (source read 2026-11-07). The component cannot be pointed here. A Node code step can. JSON result_b64 is returned when that step sends the same Accept value. The step below omits it and writes the image bytes.
Pipedream code step
export default defineComponent({
async run({ steps, $ }) {
const form = new FormData();
form.append("image_url", steps.trigger.event.image_url);
form.append("size", "auto");
const response = await fetch("https://zerobg.ai/v1.0/removebg", {
method: "POST",
headers: { "X-Api-Key": process.env.ZEROBG_API_KEY },
body: form,
});
if (!response.ok) throw new Error(await response.text());
const bytes = Buffer.from(await response.arrayBuffer());
await require("fs").promises.writeFile("/tmp/out.png", bytes);
return { path: "/tmp/out.png", credits: response.headers.get("x-credits-charged") };
},
});- Zapier: the remove.bg app is closed source. Whether it can change host was not verified. Use Webhooks by Zapier or Code by Zapier with the fetch call above. Whether Webhooks stores a binary PNG was not tested.
- Make: the remove.bg module is closed source. Use the HTTP "Make a request" module, POST, the ZeroBG URL, header X-Api-Key, and a form body. Leave parse-response off so the result stays bytes. Those labels were not clicked in the current Make UI.
- n8n: the 2026-11-07 search found no official remove.bg node. Use the HTTP Request node: POST, the ZeroBG URL, header X-Api-Key, form body (
image_fileorimage_url), response format File. Those labels were not clicked in the current n8n UI.
Node fetch, Python requests, Java
Clients you write yourself only change the URL and the key. Omit Accept: application/json when you want the image bytes. The Python example below does that.
Node fetch (JSON)
const form = new FormData();
form.append("image_url", "https://example.com/photo.jpg");
form.append("size", "auto");
const response = await fetch("https://zerobg.ai/v1.0/removebg", {
method: "POST",
headers: {
"X-Api-Key": process.env.ZEROBG_API_KEY,
Accept: "application/json",
},
body: form,
});
if (!response.ok) throw new Error(await response.text());
const { data } = await response.json();
// data.result_b64, data.foreground_top, data.foreground_left,
// data.foreground_width, data.foreground_heightPython requests
import requests
response = requests.post(
"https://zerobg.ai/v1.0/removebg",
files={"image_file": open("input.jpg", "rb")},
data={"size": "auto", "format": "png"},
headers={"X-Api-Key": "YOUR_ZEROBG_KEY"},
)
if response.status_code == 200:
open("output.png", "wb").write(response.content)
else:
print(response.status_code, response.json())Java
// java.net.http — Java 11+
var form = "image_url=" + URLEncoder.encode("https://example.com/photo.jpg", StandardCharsets.UTF_8)
+ "&size=auto";
var req = HttpRequest.newBuilder(URI.create("https://zerobg.ai/v1.0/removebg"))
.header("X-Api-Key", System.getenv("ZEROBG_API_KEY"))
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(form))
.build();
var resp = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofFile(Path.of("out.png")));Pricing
ZeroBG charges for this API in credits. Plan prices are on the pricing page.
- Each successful call uses 1 credit, including size=preview.
- A new account includes 1 HD credit. Credit-pack and sign-up credits never expire.
- Subscription credits reset to the plan amount each month and are spent first.
- Credit packs are 20 for $4.99 or 100 for $9. Any account with credits can create a key. A Pro subscription is not required.
FAQ
Is the response format the same?
A successful call returns 200 and the image bytes (image/png, image/jpeg, image/webp, or application/zip). Headers include X-Credits-Charged, X-Credits-Remaining, X-Width, X-Height, X-Foreground-Top, X-Foreground-Left, X-Foreground-Width, X-Foreground-Height, X-Type (omitted when type_level=none), and X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Send Accept: application/json by itself, including with a charset parameter, to get JSON: data.result_b64 plus data.foreground_top, foreground_left, foreground_width, and foreground_height. An Accept list that also contains another type, such as application/json, text/plain, */*, still returns the image bytes.
How do I test the move?
Create a key at /dashboard/api-keys. POST one image to https://zerobg.ai/v1.0/removebg with X-Api-Key and either image_file, image_url, or image_file_b64. A 200 response is the image. GET https://zerobg.ai/v1.0/account with the same header returns the credit balance.
What are the rate limits?
20 requests per minute on each server. A new free account can make 5 API calls per day. Unpaid accounts on the same network share a 20-call daily cap. After you buy a credit pack, or on Basic: 100 calls/day. Lifetime: 50. Pro: 300. Business: 600. A 429 response includes Retry-After. The per-minute limit is counted on each server, so it is not one global bucket.
Is a failed call charged?
Processing that fails after the credit is taken refunds that credit. The attempt still counts toward the daily limit. A request rejected before processing (missing or invalid key, invalid image, no credits, or rate limit) is not charged and does not count toward the daily limit.
Which images are accepted?
JPG, PNG, or WebP up to 25MB. Send exactly one of image_file, image_url, or image_file_b64. image_url and bg_image_url must be public http or https URLs. A data-URL prefix on image_file_b64 is stripped.
Which parameters are accepted but not applied?
add_shadow, shadow_type, and shadow_opacity are validated so an existing client does not get a 400, and no shadow is drawn. Sending both add_shadow and shadow_type returns 400 multiple_shadow_params. semitransparency is validated and not applied. type is not classified: X-Type echoes the type you sent, or other. type_level=none omits X-Type. Every successful call uses 1 credit, including size=preview.
Can I call it from a browser?
Call it from your server. Responses do not include a CORS header, so a page on another site cannot read the result, and the key stays out of client code.