# Replace Background 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) ## Response 401 fields (application/json): - `error` (object, required) - `error.code` (integer, required) Example: 123 - `error.message` (string, required) - `error.details` (string, required) - `request_id` (string, required) ## Response 403 fields (application/json): - `error` (object, required) - `error.code` (integer, required) Example: 123 - `error.message` (string, required) - `error.details` (string, required) - `request_id` (string, required) ## Response 404 fields (application/json): - `error` (object, required) - `error.code` (integer, required) Example: 123 - `error.message` (string, required) - `error.details` (string, required) - `request_id` (string, required) ## Response 415 fields (application/json): - `error` (object, required) - `error.code` (integer, required) Example: 123 - `error.message` (string, required) - `error.details` (string, required) - `request_id` (string, required) ## Response 422 fields (application/json): - `error` (object, required) - `error.code` (integer, required) Example: 123 - `error.message` (string, required) - `error.details` (string, required) - `request_id` (string, required) ## Response 429 fields (application/json): - `error` (object, required) - `error.code` (integer, required) Example: 123 - `error.message` (string, required) - `error.details` (string, required) - `request_id` (string, required) ## Response 460 fields (application/json): - `error` (object, required) - `error.code` (integer, required) Example: 123 - `error.message` (string, required) - `error.details` (string, required) - `request_id` (string, required) ## Response 5XX fields (application/json): - `error` (object, required) - `error.code` (integer, required) Example: 123 - `error.message` (string, required) - `error.details` (string, required) - `request_id` (string, required)