Editing

Eraser

Changed on

Try out this capability in Bria's sandbox

Description

The Eraser Route enables the removal of elements or specific areas from a given image.

You can define the area to be removed by providing a mask that outlines the region to be erased. There are two main ways recommended to generate these masks:

  1. Masks can be created by allowing users to draw directly on the image with a brush, for example. To access the SDK that demonstrates how to implement a brush feature in your interface, please refer to the following <a href="https://github.com/Bria-AI/js-api-sdk/blob/main/manual_brush_ui" target="_blank">link</a>.

  2. By using the /image/segment/all_masks route, which returns every region the model can identify as an individual mask. The older /objects/mask_generator route returns the same masks as a single ZIP archive and is deprecated.

Erase Modes

The composite parameter picks one of two modes. Pixel perfect (true, the default) rebuilds only the masked area and blends it into the original, so everything outside the mask stays as it was. Context aware (false) also removes what the object casts outside the mask, such as its shadow or its reflection, so the edit can't be spotted.

Output Characteristics

  • The modified image is returned at the original resolution, preserving full visual quality without any automatic resizing or downscaling.
  • With composite set to true, everything outside the mask stays as it was.
post/erase

Request

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

Request body

imagestring required

The source image to be handled by the API.
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.

maskstring required

Mask of the object to remove: white marks what to erase, black what to keep. Mask only the object, in both modes.

Mask Requirements

  • The area to erase must have a pixel value of 255 (white).
  • All other areas must have a pixel value of 0 (black).
  • The mask must have the same aspect ratio as the input image.

Supported Input Types

  • Base64-encoded string: provide the mask data directly in the request.
  • URL: provide a publicly accessible URL to the mask image.

Accepted formats: JPEG, JPG, PNG, WEBP.

Ensure that any provided URL is publicly accessible at the time of the request.

mask_type'manual' | 'automatic'

Specifies how the input mask was created.

  • manual (default) – Use when the mask was generated by a user, for example, using a brush tool.
  • automatic – Use when the mask was generated by an algorithm, such as SAM or other automated segmentation methods.
compositeboolean

Selects the erase mode.

  • true (default), pixel perfect: Only the masked area is rebuilt and blended into the original through a feathered mask edge. Everything outside the mask stays as it was. Use it for retouching where nothing else may change, such as 4K catalog photos.
  • false, context aware: The model reads the scene and also removes what the object casts outside the mask, such as its shadow or its reflection, so the edit can't be spotted. Mask only the object.
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.
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.
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