Skip to content
Image Editing
/
/
Replace Background

Overview

Bria's Image Editing API equips builders with a comprehensive suite of tools for manipulating and enhancing images, ranging from open-ended textual edits to specialized, task-specific operations.

General Image Editing (FIBO Edit)

Powered by the FIBO models family, our newest endpoints enable open-ended editing using natural language instructions. This allows for:

  • Global Edits: Modify the style, lighting, or atmosphere of an entire image via text prompts.
  • Localized Edits: Use native masking support to precisely alter specific regions while preserving the rest of the image.
  • Structured Control: Convert text instructions into structured JSON for deterministic and auditable results.

Specialized Capabilities

For focused, high-volume tasks, the API provides optimized endpoints for specific editing capabilities:

  • Background Operations: Removal, replacement, and blur.
  • Content Manipulation: Eraser (object removal) and generative fill.
  • Image Transformation: Expansion (outpainting), resolution increase (upscaling), and automatic cropping.
  • Object & Person Tools: Person modification and automatic mask generation.

Asynchronous Requests and the Status Service Bria API v2 endpoints process requests asynchronously by default. When you make an asynchronous request, the API immediately returns a request_id and a status_url instead of the final result. Use the Status Service to track the request's progress until it reaches a completed state.

See the full guide at Status Service Documentation for complete details and usage examples.

Register and get API Access
Download OpenAPI description
image-editing.json
image-editing.yaml
Languages
Servers
https://engine.prod.bria-api.com/v2/image/edit
https://engine.prod.bria-api.com/v1

v2 endpoints

Endpoints that are part of BRIA API version 2.

Operations

Remove Background

Request

Description

The Remove BG Route can be used to remove the background of an image. This route leverages Bria's newest model, RMBG 2.0. For more details and to explore the model, check out the Hugging Face demo.

Content Moderation

This endpoint includes granular content moderation controls to ensure safe usage across all stages of processing:

  • Input Image Moderation – Scans the uploaded image and stops processing if inappropriate or restricted content is detected.
  • Output Image Moderation – Evaluates the generated image and blocks the response if it violates safety guidelines.

Constraints

The Bria API currently supports only JPEG and PNG files in RGB, RGBA, or CMYK color modes. When the file is of a different type or color mode, the status code 415 will be returned.

Transparency and Customizable Binarization

This endpoint returns an image where the background is removed, and the foreground remains with varying levels of transparency, allowing for smoother edges and more natural blending when placed over different backgrounds. Additionally, this unique output provides developers with the flexibility to binarize the result—transforming it into a binary mask—by setting a custom transparency threshold according to their specific use case. A binary mask is an image where pixels are either fully visible (foreground) or fully transparent (background), commonly used in visual generative AI and image processing pipelines. This capability enables seamless integration into workflows that require clear separation between subject and background, while still offering control over how strict this separation should be.

Below is a simple Python script to demonstrate how you can binarize the output image from the API. This allows you to set your own threshold to determine which areas are considered "foreground" and which are "background."

from PIL import Image
import numpy as np

# Load the image (the output from the API)
image = Image.open('output_image.png').convert('RGBA')

# Convert to numpy array
data = np.array(image)

# Define your threshold (0-255, where 255 is fully opaque)
threshold = 128

# Apply the threshold: if alpha > threshold, set to fully opaque (255), otherwise transparent (0)
data[:, :, 3] = np.where(data[:, :, 3] > threshold, 255, 0)

# Create a new Image from the modified array
binarized_image = Image.fromarray(data)

# Save or display
binarized_image.save('binarized_output.png')
binarized_image.show()
Headers
api_tokenstringrequired
Bodyapplication/jsonrequired
imagestringrequired

The image that you would like to remove the background from. Supported input types:

  • Base64-encoded string
  • URL pointing to an image file that is publicly accessible and available at the time of processing.

Accepted formats: JPEG, JPG, PNG, WEBP.

preserve_alphaboolean

Controls whether partially transparent areas from the input image are retained in the output after background removal, if the input includes an alpha channel.

  • When true: Partially transparent pixels preserve their original alpha values in the output.
  • When false: All non-background areas in the output are rendered fully opaque.
  • Has no effect if the input image does not include an alpha channel.
Default true
syncboolean

Specifies the response mode.

  • When false (default), the request is processed asynchronously: the API immediately returns a status URL to track progress.
  • When true, the request is processed synchronously: the API hold the connection open until the proccess is complete and then returns the final image URL in the response.
Default false
visual_input_content_moderationboolean

When enabled, applies content moderation to input visual.

Expected behavior:

  • Processing stops if the image fails moderation.
  • Returns a 422 error with details about which parameter failed.
Default false
visual_output_content_moderationboolean

When enabled, applies content moderation to result visual.

Expected behavior:

  • If the modified image fails moderation, returns a 422 error.
Default false
curl -i -X POST \
  https://engine.prod.bria-api.com/v2/image/edit/remove_background \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "image": "example"
  }'

Responses

Successful operation (Synchronous Success)

Bodyapplication/json
resultobjectrequired
result.​image_urlstringrequired
result.​seedinteger
result.​refined_promptstring

Refined version of the input prompt. Returned only when:

  • The request included a prompt parameter.
  • The request did NOT include a reference_image.
request_idstringrequired
Response
application/json
{
  "result": {
    "image_url": "string",
    "seed": 0,
    "refined_prompt": "string"
  },
  "request_id": "string"
}

Replace Background

Request

Description

The Replace BG Route is used to replace the background of any image.

We offer 3 different background generation modes when generating by text: base, high contol and fast.

  • Base - clean, high quality backgrounds.
  • High_control - Stronger prompt adherence and scene context, finer control over layout and details - we recommend using this mode.
  • Fast - same core capabilities as base, optimal speed and quality balace.

This endpoint also allows replacing the background with a solid color of your choice. You can specify a hex color code (e.g., #FF5733) in the prompt to control the background color.

Here are some examples:

original image:

prompt: in a parking lot

result:

Content Moderation

This endpoint includes granular content moderation controls to ensure safe usage across all stages of processing:

  • Prompt Moderation – Validates the provided prompt and rejects requests containing unsafe or prohibited terms before processing starts.
  • Input Image Moderation – Scans the uploaded image and stops processing if inappropriate or restricted content is detected.
  • Output Image Moderation – Evaluates the generated image and blocks the response if it violates safety guidelines.
Headers
api_tokenstringrequired

API token associated with the organization.

Bodyapplication/json
imagestringrequired

The image that you would like to remove the background from. Supported input types:

  • Base64-encoded string
  • URL pointing to an image file that is publicly accessible and available at the time of processing.

Accepted formats: JPEG, JPG, PNG, WEBP.

modestring

Selects the background-generation mode. Relevant only when describing the background by text.

  • Base - clean, high quality backgrounds.
  • High_control - stronger prompt adherence and scene context, finer control over layout and details.
  • Fast - same core capabilities as base, optimal speed and quality balace.
Default "high_control"
Enum"base""high_control""fast"
ref_imagesstring

One or more reference images to guide the background generation.

Supported Input Types

  • Base64-encoded string – provide the image data directly in the request.
  • URL – provide a publicly accessible URL to the image.
  • List – multiple images can be supplied as a list of Base64 strings or URLs.

Usage Constraints

  • You must provide either ref_images or prompt, but not both.
  • Accepted formats: JPEG, JPG, PNG, WEBP.

All provided images must be accessible and in a supported format at the time of processing.

enhance_ref_imagesboolean

When set to true, additional logic processes the included reference image to make adjustments for optimal results.

Default true
promptstring

Text description of the new scene or background for the provided image. Either ref_images or prompt has to be provided but not both. Bria currently supports prompts in English only, excluding special characters.

Prompt length guidelines per mode:

  • base / fast: ~50–60 words
  • high_control: ~90–110 words
refine_promptboolean

When true, an additional logic takes the prompt that was included and adjusts it to achieve optimal results.

Default true
prompt_content_moderationboolean

When enabled (default: true), the input prompt is moderated before processing.

Expected Behavior

  • The prompt is scanned for NSFW content and terms that violate Bria’s ethical guidelines.
  • If the prompt fails moderation, the request is blocked and the API responds with a 422 error.

Prompt length guidelines per mode:

  • base / fast: ~50–60 words
  • high_control: ~90–110 words
Default true
negative_promptstring

Elements or features that should be excluded from the generated scene. This parameter is optional and is available only when fast=false. Bria currently supports descriptions in English only.

original_qualityboolean

When true, the output image retains the original input image's size; otherwise, the image is scaled to 1 megapixel (1MP) while preserving its aspect ratio.

Default false
force_background_detectionboolean

When true, forces background detection and removal, even if the original image already contains an alpha channel. Useful for refining existing foreground/background separation or ignoring unnecessary alpha channels.

Default false
syncboolean

Specifies the response mode.

  • When false (default), the request is processed asynchronously: the API immediately returns a status URL to track progress.
  • When true, the request is processed synchronously: the API hold the connection open until the proccess is complete and then returns the final image URL in the response.
Default false
visual_output_content_moderationboolean

When enabled, applies content moderation to result visual.

Expected behavior:

  • If the modified image fails moderation, returns a 422 error.
Default false
seedinteger

You can choose whether you want your generated results to be random or predictable. You can recreate the same result in the future by using the seed value of a result from the response. You can exclude this parameter if you are not interested in recreating your results. This parameter is optional.

curl -i -X POST \
  https://engine.prod.bria-api.com/v2/image/edit/replace_background \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "image": "example",
    "mode": "high_control",
    "prompt": "in a living room interior, on a kitchen counter"
  }'

Responses

Successful operation (Synchronous Success)

Bodyapplication/json
resultobjectrequired
result.​image_urlstringrequired
result.​seedinteger
result.​refined_promptstring

Refined version of the input prompt. Returned only when:

  • The request included a prompt parameter.
  • The request did NOT include a reference_image.
request_idstringrequired
Response
application/json
{
  "result": {
    "image_url": "string",
    "seed": 0,
    "refined_prompt": "string"
  },
  "request_id": "string"
}

Erase Foreground

Request

Description

The Erase Foreground endpoint removes the primary subject (foreground) from the input image and intelligently generates the background to fill the erased area.

Output Characteristics

  • Returns the edited image at its original resolution, ensuring full visual fidelity without any automatic resizing or downscaling.
  • Only the foreground is removed; all other areas remain unaltered, preserving pixel-perfect accuracy in untouched regions.
  • When preserve_alpha=true and the input image includes an alpha channel, the output maintains original transparency values (both full and partial).

Content Moderation

This endpoint includes granular content moderation controls to ensure safe usage across all stages of processing:

  • Input Image Moderation – Scans the uploaded image and stops processing if inappropriate or restricted content is detected.
  • Output Image Moderation – Evaluates the generated image and blocks the response if it violates safety guidelines.
Headers
api_tokenstringrequired
Bodyapplication/json
imagestringrequired

The image that you would like to remove the background from. Supported input types:

  • Base64-encoded string
  • URL pointing to an image file that is publicly accessible and available at the time of processing.

Accepted formats: JPEG, JPG, PNG, WEBP.

preserve_alphaboolean

Controls whether the alpha channel values from the input image are retained in the output, if the input includes an alpha channel.

  • When true: The output image maintains the original transparency of fully and partially transparent pixels.
  • When false: The output image is fully opaque.
  • Has no effect if the input image does not include an alpha channel.
Default true
syncboolean

Specifies the response mode.

  • When false (default), the request is processed asynchronously: the API immediately returns a status URL to track progress.
  • When true, the request is processed synchronously: the API hold the connection open until the proccess is complete and then returns the final image URL in the response.
Default false
visual_input_content_moderationboolean

When enabled, applies content moderation to input visual.

Expected behavior:

  • Processing stops if the image fails moderation.
  • Returns a 422 error with details about which parameter failed.
Default false
visual_output_content_moderationboolean

When enabled, applies content moderation to result visual.

Expected behavior:

  • If the modified image fails moderation, returns a 422 error.
Default false
curl -i -X POST \
  https://engine.prod.bria-api.com/v2/image/edit/erase_foreground \
  -H 'Content-Type: application/json' \
  -H 'api_token: string' \
  -d '{
    "image_url": "example"
  }'

Responses

Successful operation (Synchronous Success)

Bodyapplication/json
resultobjectrequired
result.​image_urlstringrequired
request_idstringrequired
Response
application/json
{
  "result": {
    "image_url": "string"
  },
  "request_id": "string"
}

v1 endpoints

Endpoints that are part of BRIA API version 1.

Operations