Skip to content
Image Editing
/
/
Replace Background

Replace Background

Request

Try out this capability in Bria's sandbox

Description

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

We offer 4 different background generation modes when generating by text: base, high control, fast and fibo2.

  • Base - clean, high quality backgrounds.
  • High_control - Stronger prompt adherence and scene context, finer control over layout and details. Use this mode when you need ref_images. The API default.
  • Fast - same core capabilities as base, optimal speed and quality balace.
  • Fibo2 - the new background is generated by Fibo 2, and the original product is pasted back over it - we recommend using this mode for text prompts. It does not accept ref_images.

Fibo 2 Mode

Set mode to fibo2 to generate the background with Fibo 2. Bria cuts the product out of your image, Fibo 2 builds a new scene around it from your prompt, and the original product pixels are pasted back over the result, so the product itself is never regenerated. fibo2 takes a text prompt only: sending ref_images returns 400. negative_prompt is ignored in this mode.

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.
Security
api_token
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.
  • Fibo2 - the background is generated by Fibo 2 and the original product is pasted back over it. Text prompt only; ref_images returns 400.
Default:"high_control"
Enum:"base""high_control""fast""fibo2"
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:false
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
  • fibo2: ~90–110 words
refine_promptboolean

When true, an LLM rewrites prompt into a more detailed scene description, using the product in the image as context, and the background is generated from the rewritten prompt. The rewritten prompt is returned as refined_prompt.

Applies in every mode, fibo2 included. Ignored when ref_images is sent.

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
  • fibo2: ~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. Ignored in fibo2 mode. 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
webhook_urlstring, (uri)

Optional URL for receiving the result via webhook when the async job completes. See webhooks.

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.

POST
/replace_background
from bria_client import BriaSyncClient

client = BriaSyncClient()  # reads BRIA_API_TOKEN

response = client.run(
    endpoint="image/edit/replace_background",
    payload={
        "image": "https://labs-assets.bria.ai/sandbox-example-inputs/replace_bg_example_image.jpg",
        "prompt": "Resting on a light pink circular platform placed on a bright red floor in a photo studio. The background is a vivid red wall with subtle vertical lines. Surrounding the platform are numerous 3D red poppy flowers in varying sizes. Sliced and whole grapefruits are arranged around the base of the platform, adding fresh color contrast. Lit evenly by soft studio lighting. Shot from a front angle.",
        "mode": "fibo2",
    },
)
print(response.result.image_url)

Responses

Successful operation (Synchronous Success)

Bodyapplication/json
resultobject(result)required
request_idstringrequired
Response
{
  "result": {
    "image_url": "string",
    "seed": 0,
    "refined_prompt": "string"
  },
  "request_id": "string"
}