# Replace Background

Try out this capability in Bria's sandbox


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.

Endpoint: POST /replace_background

## Header parameters:

  - `api_token` (string, required)
    API token associated with the organization.

## Request fields (application/json):

  - `image` (string, required)
    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.

  - `mode` (string)
    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.
    Enum: "base", "high_control", "fast"

  - `ref_images` (string)
    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_images` (boolean)
    When set to true, additional logic processes the included reference image to make adjustments for optimal results.

  - `prompt` (string)
    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_prompt` (boolean)
    When true, an additional logic takes the prompt that was included and adjusts it to achieve optimal results.

  - `prompt_content_moderation` (boolean)
    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

  - `negative_prompt` (string)
    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_quality` (boolean)
    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.

  - `force_background_detection` (boolean)
    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.

  - `sync` (boolean)
    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.

  - `visual_output_content_moderation` (boolean)
    When enabled, applies content moderation to result visual.

Expected behavior:
- If the modified image fails moderation, returns a 422 error.

  - `seed` (integer)
    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.

## Response 200 fields (application/json):

  - `result` (object, required)

  - `result.image_url` (string, required)

  - `result.seed` (integer)

  - `result.refined_prompt` (string)
    Refined version of the input prompt.
Returned only when:
- The request included a prompt parameter.
- The request did NOT include a reference_image.

  - `request_id` (string, required)

## Response 202 fields (application/json):

  - `request_id` (string, required)

  - `status_url` (string, required)

## Response 400 fields (application/json):

  - `error` (object, required)

  - `error.code` (integer, required)
    Example: 123

  - `error.message` (string, required)

  - `error.details` (string, required)

  - `request_id` (string, required)