Fixing color distortions: why the despill parameter changes your subject's tint

What despill actually does in this API

In the API, despill runs as a post-processing step after the mask has already been created and after the image has been resized to the requested output size. It happens before any optional solid background replacement through bg_color.

This feature specifically targets green spill. That matters because it is not a generic hue correction system. It is intentionally targeting green tones. In other words, this step is designed to reduce unwanted greenish contamination, especially around edges and semi-transparent areas.

• despill=false -> no green spill correction step is applied
• despill=true -> a green-spill correction pass runs after resizing and before bg_color flattening

Why it can change your subject's tint

The despill step works in Lab color space and specifically pushes greenish pixels back toward neutral. That is why it helps reduce green halos, but it also means it can alter the way some real subject colors look. If a shirt, product, reflection, accessory, or part of the subject already contains legitimate green information, the correction can reduce some of that too.

The API does try to restore luminance after the despill adjustment, which helps preserve brightness and reduces obvious artifacts. But preserving brightness is not the same thing as preserving the exact original chroma. So a result can keep similar lightness while still looking a bit less green or slightly different in tint.

Common symptoms of despill-related color change

These are the most common things users notice when despill=true changes the look of the result:

• Green edge fringe around hair
• Green cast on shoulders or cheek edges
• Tint shift on reflective products
• Less green halo but slightly different subject color
• Better edge cleanup on green-screen-like contamination
• Unwanted change to naturally green clothing or objects

The key pattern is this: edges often look cleaner, but some subjects may also look slightly less green, slightly warmer, or just a little different than the original.

When despill helps the most

Despill is most useful when the image actually contains green contamination that needs correction. Common examples include:

• Green spill around hair edges
• Green cast from a green-screen-like setup
• Reflective surfaces picking up green background tones
• Fine translucent edges that retain green fringe
• Subjects photographed against saturated green environments

In those cases, the color shift is often a worthwhile trade: a small tint change may be better than an obvious green halo around the subject.

When to leave despill off

If the subject already looks natural and you do not see green contamination, there is usually no reason to enable despill. Turning it on in those cases can create unnecessary color changes with little visual benefit.

You should be especially cautious when the subject genuinely contains green tones, such as:

• Green clothing or uniforms
• Plants or natural green products
• Green packaging or branding elements
• Reflective items with real green surfaces
• Product photography where accurate color matters

Minimal curl comparison

First run the image without despill:

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' \
-F 'despill=false' \
-o output-no-despill.png

Then run the same image with despill enabled:

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' \
-F 'despill=true' \
-o output-despill.png

JSON examples

Despill off:

{
  "image_base64": "BASE64_IMAGE_HERE",
  "format": "png",
  "despill": false
}

Despill on:

{
  "image_base64": "BASE64_IMAGE_HERE",
  "format": "png",
  "despill": true
}

Python comparison workflow

The quickest reliable test is to save both versions side by side and inspect them visually:

import requests

def run(despill, output_name):
    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",
                "despill": str(despill).lower()
            },
            timeout=120,
        )

    response.raise_for_status()
    with open(output_name, "wb") as out:
        out.write(response.content)

run(False, "no_despill.png")
run(True, "with_despill.png")

Node.js comparison workflow

The same approach works well in Node.js:

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

async function run(inputPath, outputPath, despill) {
  const form = new FormData();
  form.append("image_file", fs.createReadStream(inputPath));
  form.append("format", "png");
  form.append("despill", String(despill));

  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
  });

  if (!response.ok) {
    throw new Error(await response.text());
  }

  const buffer = Buffer.from(await response.arrayBuffer());
  fs.writeFileSync(outputPath, buffer);
}

(async () => {
  await run("./input.jpg", "./no_despill.png", false);
  await run("./input.jpg", "./with_despill.png", true);
})();

How bg_color can change what you notice

Because despill runs before bg_color replacement, the background you composite onto can change how obvious the tint shift feels. A small color change that looks subtle on transparency may become much more noticeable when placed on a white, gray, or branded solid background.

So if you use bg_color, compare the final flattened output too, not just the raw cutout.

Despill is not a universal color correction tool

This is one of the biggest sources of confusion. Users often expect despill to behave like a smart enhancement pass that universally improves the image. That is not what this parameter is doing.

In BackgroundErase, it is a targeted spill-removal step with a very specific bias: it tries to reduce greenish contamination. That makes it useful, but also selective. Whether it improves or harms a given image depends on whether green spill was actually the problem in the first place.

Final recommendation

If your subject looks slightly tinted or different with despill=true, that does not necessarily mean the API is malfunctioning. It usually means the green-spill correction did exactly what it was designed to do, and in this image the tradeoff may not be worth it.

• Use despill=false as your baseline
• Only enable despill=true when you see real green spill
• Compare edge cleanup against natural subject color
• Be cautious with genuine green objects or clothing
• Judge the final flattened result too if you use bg_color

For most workflows, the right answer is simple: despill should be opt-in, not always-on.