Editing

Guided Remove Background

Changed on

Description

The Guided Remove Background endpoint removes the background and lets you say in plain words what the cutout keeps. It starts from the same cut as Remove Background and changes only what the prompt names:

  • Add something the default cut drops: "the person with the mat and the plant".
  • Drop something the default cut keeps: "the woman at her desk without the lamp".
  • Narrow the cut to one item: "only the chair".

A missing or blank prompt returns the standard Remove Background cutout.

Example with the prompt "the person with the mat and the plant":

<table> <tr> <th style="text-align: center;">Input</th> <th style="text-align: center;">Result</th> </tr> <tr> <td align="center" style="vertical-align: middle;"> <img src="https://labs-assets.bria.ai/api-examples/guided-remove-background/yoga_studio_input.jpg" width="250" style="border-radius: 8px;"> </td> <td align="center" style="vertical-align: middle;"> <img src="https://labs-assets.bria.ai/api-examples/guided-remove-background/yoga_studio_with_mat_and_plant_result.png" width="250" style="border-radius: 8px;"> </td> </tr> </table>

Output Characteristics

  • Returns the original image at its original resolution with a new alpha channel. No pixels are repainted.
  • Anything the prompt drops becomes transparent, including parts of the main subject.
  • When preserve_alpha=true and the input image includes an alpha channel, the output maintains original transparency values (both full and partial).

Processing Time

A request with a prompt takes about 15 to 20 seconds. sync defaults to false, so the API returns a request_id and a status_url right away. Get the result from the status endpoint or with a webhook.

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.
post/remove_background/guided

Request

  • Base URL: https://engine.prod.bria-api.com/v2/image/edit
  • URL: https://engine.prod.bria-api.com/v2/image/edit/remove_background/guided
  • Auth: API key in header api_token

Request body

imagestring 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.

promptstring

Optional. Plain words that change what the default cut keeps. Add to it, drop from it, or narrow it to one item, for example:

  • "the person with the mat and the plant"
  • "the woman at her desk without the lamp"
  • "only the chair"

A missing or blank prompt returns the standard Remove Background cutout.

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.
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 holds the connection open until the process is complete and then returns the final image URL in the response.
webhook_urlstring uri

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

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.
visual_output_content_moderationboolean

When enabled, applies content moderation to result visual.

Expected behavior:

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

Response

Successful operation (Synchronous Success)

request_idstring required

Changes