Resolving 400: format must be one of...

What this error looks like

A typical response looks like this:

{
  "error": {
    "code": "bad_request",
    "message": "format must be one of ['bmp', 'gif', 'jpg', 'png', 'tiff', 'webp']",
    "status": 400,
    "request_id": "..."
  }
}

In the API, this error comes from the format normalization step, where the API maps known aliases and then checks the final value against the supported output format set.

Supported output formats

The canonical output formats accepted by your API are:

• png
• jpg
• webp
• bmp
• tiff
• gif

If you want the most predictable starting point, use png first. It is the default format in your API, it preserves transparency, and it is the safest format for most background removal workflows.

Accepted aliases

The API also accepts a small set of aliases and normalizes them internally:

• jpeg maps to jpg
• jpe maps to jpg
• jfif maps to jpg
• tif maps to tiff

So jpeg is fine because it maps to jpg, and tif is fine because it maps to tiff. But formats outside that accepted set will still fail.

Common misunderstanding: input format vs output format

This error often happens because a user thinks format is declaring the type of the file they uploaded. That is not how this API uses it. The uploaded source image can be JPG, PNG, WebP, HEIC, or another supported input type, but format only describes what you want back.

That means requests like these are perfectly normal:

• Upload JPG, request PNG output
• Upload PNG, request JPG output
• Upload HEIC, request WebP output
• Upload WebP, request TIFF output

Quick checklist

Before debugging anything else, walk through this:

1. Check the value you are sending in format
2. Use one of the supported canonical output formats
3. If you use jpeg or tif, remember they are aliases
4. Do not confuse the input image type with the requested output format
5. If unsure, remove format entirely and let the API default to png
6. Retry with one minimal curl request
7. Add your final preferred format back once the baseline works

Start with a minimal known-good request

The easiest way to isolate the issue is to send one simple request with a clearly supported format. PNG is the safest baseline:

curl -H 'x-api-key: YOUR_API_KEY' \
-f https://api.backgrounderase.com/v2 \
-F 'image_file=@/absolute/path/to/input.jpg' \
-F 'format=png' \
-o output.png

If that succeeds, your problem is just the requested output format value, not the rest of the integration.

Other valid examples

JPG output:

curl -H 'x-api-key: YOUR_API_KEY' \
-f https://api.backgrounderase.com/v2 \
-F 'image_file=@/absolute/path/to/input.png' \
-F 'format=jpg' \
-o output.jpg

WebP output:

curl -H 'x-api-key: YOUR_API_KEY' \
-f https://api.backgrounderase.com/v2 \
-F 'image_file=@/absolute/path/to/input.jpg' \
-F 'format=webp' \
-o output.webp

JSON clients can do the same:

{
  "image_base64": "BASE64_IMAGE_HERE",
  "format": "png",
  "size": "full"
}

Alias example:

{
  "image_base64": "BASE64_IMAGE_HERE",
  "format": "jpeg"
}

Common invalid format values

These kinds of values commonly trigger the error:

• pdf
• svg
• heic
• heif
• avif
• raw
• jpeg2000
• mp4
• transparent-png
• image/png

Some of these are real image formats in the general world, but they are not valid output format values in this API.

Special note about JPG, BMP, and GIF

The API treats jpg, bmp, and gif as opaque-only output formats. That means if the result still has transparency, the API flattens it onto a background color, defaulting to white if needed.

So if you want to preserve transparency, PNG or WebP is usually the better target. If you want a flat white-background result, JPG is often a better fit.

Default behavior if you omit format

Another useful detail is that the default format is png. That means if you are unsure whether the format field is the problem, you can temporarily remove it and let the API fall back to PNG.

This is often the fastest way to confirm that everything else in the request is fine.

Python example for isolating the issue

In Python, the simplest baseline is a multipart request with a supported format like PNG:

import requests

with open("input.jpg", "rb") as f:
    response = requests.post(
        "https://api.backgrounderase.com/v2",
        headers={"x-api-key": "YOUR_API_KEY"},
        files={"image_file": f},
        data={"format": "png"},
        timeout=120,
    )

print(response.status_code)
print(response.text[:1000])

Node.js example for isolating the issue

In Node.js, use a small known-good request first and confirm the API accepts the format before layering on more logic:

const fs = require("fs");
const FormData = require("form-data");

async function testRequest() {
  const form = new FormData();
  form.append("image_file", fs.createReadStream("./input.jpg"));
  form.append("format", "png");

  const response = await fetch("https://api.backgrounderase.com/v2", {
    method: "POST",
    headers: {
      "x-api-key": process.env.BG_ERASE_API_KEY,
      ...form.getHeaders()
    },
    body: form
  });

  console.log(response.status);
  console.log(await response.text());
}

testRequest();

Why this happens in real integrations

In production systems, this error often comes from values being generated dynamically by the app, UI, or workflow builder. A frontend might pass a MIME type like image/png instead of png. Another system might reuse the uploaded file extension and pass something like heic even though the output encoder does not support that value.

It is also common for teams to accidentally pass marketing or app-specific labels like transparent-png or photo, which may make sense internally but are not valid API format names.

Final resolution path

If you are seeing format must be one of..., the cleanest path is:

• Use a supported output format like png, jpg, or webp
• Remember that jpeg and tif are aliases
• Do not confuse source file type with returned output type
• Remove format entirely if you want the API default of PNG
• Retry with a minimal direct request first
• Then map your app’s desired output into a valid API value

In most cases, the issue is resolved immediately once the requested output format is normalized into one of the accepted values.