Birefnet API

• Birefnet
• V2

Endpoint: POST https://fal.run/fal-ai/birefnet Endpoint ID: fal-ai/birefnet

Try it in the Playground

Run this model interactively with your own prompts.

​

Quick Start

Python

JavaScript

cURL

import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/birefnet",
    arguments={
        "image_url": "https://storage.googleapis.com/falserverless/example_inputs/birefnet-input.jpeg"
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)

​

Input Schema

​

model

ModelEnum

default:"General Use (Light)"

Model to use for background removal. The ‘General Use (Light)’ model is the original model used in the BiRefNet repository. The ‘General Use (Heavy)’ model is a slower but more accurate model. The ‘Portrait’ model is a model trained specifically for portrait images. The ‘General Use (Light)’ model is recommended for most use cases.The corresponding models are as follows:

• ‘General Use (Light)’: BiRefNet-DIS_ep580.pth
• ‘General Use (Heavy)’: BiRefNet-massive-epoch_240.pth
• ‘Portrait’: BiRefNet-portrait-TR_P3M_10k-epoch_120.pth Default value: "General Use (Light)"

Possible values: General Use (Light), General Use (Heavy), Portrait

​

operating_resolution

OperatingResolutionEnum

default:"1024x1024"

The resolution to operate on. The higher the resolution, the more accurate the output will be for high res input images. Default value: "1024x1024"Possible values: 1024x1024, 2048x2048

​

output_mask

boolean

default:"false"

Whether to output the mask used to remove the background

​

refine_foreground

boolean

default:"true"

Whether to refine the foreground using the estimated mask Default value: true

​

sync_mode

boolean

default:"false"

If True, the media will be returned as a data URI and the output data won’t be available in the request history.

​

image_url

string

required

URL of the image to remove background from

​

output_format

OutputFormatEnum

default:"png"

The format of the output image Default value: "png"Possible values: webp, png, gif

​

Output Schema

​

image

ImageFile

required

Image with background removed

​

mask_image

ImageFile

Mask used to remove the background

​

Input Example

{
  "model": "General Use (Light)",
  "operating_resolution": "1024x1024",
  "output_mask": false,
  "refine_foreground": true,
  "sync_mode": false,
  "image_url": "https://storage.googleapis.com/falserverless/example_inputs/birefnet-input.jpeg",
  "output_format": "png"
}

​

Output Example

{
  "image": {
    "content_type": "image/png",
    "file_name": "birefnet-output.png",
    "height": 1024,
    "url": "https://storage.googleapis.com/falserverless/example_outputs/birefnet-output.png",
    "width": 1024
  }
}

Endpoint: POST https://fal.run/fal-ai/birefnet/v2 Endpoint ID: fal-ai/birefnet/v2

Try it in the Playground

Run this model interactively with your own prompts.

​

Quick Start

Python

JavaScript

cURL

import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "fal-ai/birefnet/v2",
    arguments={
        "image_url": "https://storage.googleapis.com/falserverless/example_inputs/birefnet-input.jpeg"
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)

​

Examples

​

Input Schema

​

model

ModelEnum

default:"General Use (Light)"

Model to use for background removal. The ‘General Use (Light)’ model is the original model used in the BiRefNet repository. The ‘General Use (Light 2K)’ model is the original model used in the BiRefNet repository but trained with 2K images. The ‘General Use (Heavy)’ model is a slower but more accurate model. The ‘Matting’ model is a model trained specifically for matting images. The ‘Portrait’ model is a model trained specifically for portrait images. The ‘General Use (Dynamic)’ model supports dynamic resolutions from 256x256 to 2304x2304. The ‘General Use (Light)’ model is recommended for most use cases.The corresponding models are as follows:

• ‘General Use (Light)’: BiRefNet
• ‘General Use (Light 2K)’: BiRefNet_lite-2K
• ‘General Use (Heavy)’: BiRefNet_lite
• ‘Matting’: BiRefNet-matting
• ‘Portrait’: BiRefNet-portrait
• ‘General Use (Dynamic)’: BiRefNet_dynamic Default value: "General Use (Light)"

Possible values: General Use (Light), General Use (Light 2K), General Use (Heavy), Matting, Portrait, General Use (Dynamic)

​

operating_resolution

OperatingResolutionEnum

default:"1024x1024"

The resolution to operate on. The higher the resolution, the more accurate the output will be for high res input images. The ‘2304x2304’ option is only available for the ‘General Use (Dynamic)’ model. Default value: "1024x1024"Possible values: 1024x1024, 2048x2048, 2304x2304

​

output_mask

boolean

default:"false"

Whether to output the mask used to remove the background

​

refine_foreground

boolean

default:"true"

Whether to refine the foreground using the estimated mask Default value: true

​

sync_mode

boolean

default:"false"

If True, the media will be returned as a data URI and the output data won’t be available in the request history.

​

image_url

string

required

URL of the image to remove background from

​

output_format

OutputFormatEnum

default:"png"

The format of the output image Default value: "png"Possible values: webp, png, gif

​

mask_only

boolean

default:"false"

Whether to return only the segmentation mask without applying it to the image. When set to True, only the mask will be returned and foreground refinement will be skipped. Useful for reducing computation and data transfer when only the mask is needed.

​

Output Schema

​

image

ImageFile

required

Image with background removed. When mask_only is True, this contains the segmentation mask instead.

​

mask_image

ImageFile

Mask used to remove the background

​

Input Example

{
  "model": "General Use (Light)",
  "operating_resolution": "1024x1024",
  "output_mask": false,
  "refine_foreground": true,
  "sync_mode": false,
  "image_url": "https://storage.googleapis.com/falserverless/example_inputs/birefnet-input.jpeg",
  "output_format": "png",
  "mask_only": false
}

​

Output Example

{
  "image": {
    "content_type": "image/png",
    "file_name": "birefnet-output.png",
    "height": 1024,
    "url": "https://storage.googleapis.com/falserverless/example_outputs/birefnet-output.png",
    "width": 1024
  }
}

​

Performance

​

Precision Segmentation Architecture

• Three-tier model selection: Choose Light (BiRefNet-DIS_ep580) for speed, Heavy (BiRefNet-massive-epoch_240) for complex scenes, or Portrait (BiRefNet-portrait-TR_P3M_10k-epoch_120) for face-optimized segmentation based on your accuracy requirements
• Scalable resolution processing: Operate at 1024x1024 for standard workflows or 2048x2048 (4MP) for high-resolution source images requiring maximum edge fidelity
• Optional foreground refinement: Enable refine_foreground to apply mask-guided enhancement that preserves subject detail while ensuring clean transparency
• Dual output capability: Export both the background-removed image and the raw segmentation mask for manual compositing or downstream processing pipelines

​

Technical Specifications

​

How It Stacks Up

​

Limitations

• model restricted to: General Use (Light), General Use (Heavy), Portrait
• operating_resolution restricted to: 1024x1024, 2048x2048
• output_format restricted to: webp, png, gif
• model restricted to: General Use (Light), General Use (Light 2K), General Use (Heavy), Matting, Portrait, General Use (Dynamic)
• operating_resolution restricted to: 1024x1024, 2048x2048, 2304x2304