Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bfl.ml/llms.txt

Use this file to discover all available pages before exploring further.

FLUX Erase removes the masked object and reconstructs the scene behind it with contextually coherent content in a single call. Useful for product photography clean-up, removing unwanted elements, scene simplification, or privacy-aware image editing.

​
Example output

Drag the slider to compare the input image with the masked region outlined in green (left) against the cleaned result (right).

​
More examples

​
Endpoint

Submit an erase job: 
POST https://api.bfl.ai/v1/flux-tools/erase-v1
x-key: $BFL_API_KEY
Poll for the result: 
GET https://api.bfl.ai/v1/get_result?id=<TASK_ID>
x-key: $BFL_API_KEY

​
Quick start

The API uses an asynchronous workflow:
1

Prepare a mask

Create a black/white PNG at the same resolution as your input image. White (255) marks the pixels to remove, black (0) marks pixels to keep.
2

Submit an erase request

POST the input image and mask (both base64-encoded) to the endpoint. No prompt is needed — the model uses a built-in erase instruction.
3

Poll for the result

Use the returned polling_url to check status until the image is ready.
#!/usr/bin/env python3
import base64
import os
import time
import requests

API_KEY = os.environ["BFL_API_KEY"]
BASE = "https://api.bfl.ai"
HEADERS = {"accept": "application/json", "x-key": API_KEY, "Content-Type": "application/json"}

IMAGE_PATH = "/path/to/input.png"
MASK_PATH = "/path/to/mask.png"  # White (255) = remove, Black (0) = keep
DILATE_PIXELS = 10               # Expand mask edges for cleaner removal

with open(IMAGE_PATH, "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

with open(MASK_PATH, "rb") as f:
    mask_b64 = base64.b64encode(f.read()).decode()

payload = {
    "image": image_b64,
    "mask": mask_b64,
    "dilate_pixels": DILATE_PIXELS,
    "output_format": "png",
}

submit = requests.post(f"{BASE}/v1/flux-tools/erase-v1", headers=HEADERS, json=payload)
submit.raise_for_status()
meta = submit.json()

task_id = meta["id"]
poll_url = meta.get("polling_url", f"{BASE}/v1/get_result?id={task_id}")

while True:
    r = requests.get(poll_url, headers={"accept": "application/json", "x-key": API_KEY})
    r.raise_for_status()
    result = r.json()

    status = result.get("status")
    if status == "Ready":
        print("Result URL:", result["result"]["sample"])
        break
    if status in {"Error", "Request Moderated", "Content Moderated", "Task not found"}:
        raise RuntimeError(f"Erase failed with status: {status} | payload: {result}")

    time.sleep(1)

​
Request parameters

ParameterTypeRequiredDescription
imagebase64 stringYesInput image
maskbase64 stringYesBlack/white mask. White (255) = remove, black (0) = keep. Must match the input image dimensions
dilate_pixelsintegerNoPixels to dilate the mask before removal. Range 0–100, default 10. Helps the model fully cover object edges
output_formatstringNopng (default) or jpeg
No prompt is sent by the caller — the server applies a fixed erase instruction internally.

​
Response format

​
Initial response

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "polling_url": "https://api.bfl.ai/v1/get_result?id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

​
Polling response (success)

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "Ready",
  "result": {
    "sample": "https://delivery.bfl.ai/..."
  }
}
When status is "Ready", use result.sample.
Signed delivery URLs are only valid for 10 minutes. Retrieve your result within this timeframe.

​
Mask guidelines

  • Format: black-and-white PNG at the same resolution as the input image.
  • White (255) = pixels to remove. Black (0) = pixels to keep.
  • The server converts the binary mask to a green fill internally — callers only send the binary mask.
  • Dilation (dilate_pixels): expanding the mask by a few pixels typically improves removal quality by ensuring the model fully covers object edges. For typical SAM (Segment Anything) masks, start with 10.

​
Tips for best results

  • Use a mask that fully covers the object you want to remove. If the mask is leaving an edge, increase dilate_pixels.
  • For objects with soft edges (hair, fur, smoke) that masks rarely capture cleanly, use a higher dilate_pixels value (15–20).
  • The model was trained on images at ~1 megapixel across 9 aspect ratios from 1:2 to 2:1. Inputs close to these resolutions produce the best results — significant deviations may reduce quality.

​
Troubleshooting

  • 403 Forbidden — your API key is missing or your project doesn’t have access to this endpoint.
  • 422 / validation errors — check base64 encoding and that the mask matches the input image dimensions exactly.
  • Visible halo around removed object — increase dilate_pixels.
  • Reconstruction looks off — verify the mask covers the entire object including shadows or reflections you want gone.
For the full list of HTTP status codes and polling response types returned by the API, see the Errors reference.