--- title: "Guided Remove Background" method: POST path: "/remove_background/guided" tags: ["Editing"] --- # Guided Remove Background `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` **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](/image-editing/editing/background-remove) 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":
Input Result
**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](/status) or with a [webhook](/getting-started/async-requests#webhooks). **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. ## Request body - object - `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**. - `prompt` string: 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_alpha` boolean: 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. - `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 holds the connection open until the process is complete and then returns the final image URL in the response. - `webhook_url` string, uri: Optional URL for receiving the result via webhook when the async job completes. See [webhooks](/getting-started/async-requests#webhooks). - `visual_input_content_moderation` boolean: 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_moderation` boolean: When enabled, applies content moderation to result visual. Expected behavior: - If the modified image fails moderation, returns a 422 error. ## Response `200` Successful operation (Synchronous Success) - SyncSuccessResponse - `result` object, required - `image_url` string, required - `request_id` string, required ## Other responses - `202`: Accepted (Asynchronous). You can track the progress and retrieve the final result using the status endpoint. For more details, refer to the [status endpoint](/status) section. - `400`: Bad request. - `401`: Unauthorized. - `403`: Forbidden. - `404`: Not found. Image could not be found at the provided URL. - `415`: Unsupported media type. - `422`: Unprocessable Entity - `429`: Request limit exceeded. - `460`: Failed to download image. - `5XX`: **Internal Server Error.** A critical failure occurred in Bria's infrastructure, preventing the endpoint from responding. - This response indicates a service outage or unexpected runtime failure. - Check [Bria's Status Page](https://status.bria.ai) for real-time updates. - Contact [Support](mailto:support@bria.ai). ## Changes - **2026-10-11** `b90f29dff9a5`: 1 info - endpoint added [Operation history](https://skmtc.dev/bria-ai/apis/image-editing-api-reference/changes/remove_background/guided/post.md) --- [API](https://skmtc.dev/bria-ai/apis/image-editing-api-reference.md) · [All operations](https://skmtc.dev/bria-ai/apis/image-editing-api-reference/llms.txt) · [OpenAPI document](https://skmtc.dev/bria-ai/apis/image-editing-api-reference/revisions/ff15f86ae88f?raw)