# Generative Fill

[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/generative-fill)
**Description**
The *GenFill Route* enables the generation of objects by prompt in a specific region of an image.
You can define the area for object generation by using a mask that outlines the region where the object will be created. Our model is optimized to work seamlessly with blob-shaped masks.
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>.
**Output Characteristics**
- The modified image is returned at the original resolution, preserving full visual quality without any automatic resizing or downscaling.
- All areas outside the provided mask remain completely unchanged, ensuring pixel-perfect preservation of unedited regions.
- If the input includes an alpha channel and `preserve_alpha=true`, the original transparency values (both full and partial) are maintained in the output.

**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 /gen_fill
Security: api_token

## Request fields (application/json):

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

  - `mask` (string, required)
    The binary mask image that defines the region where object generation will occur.
**Mask Requirements**
- The region to generate content 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.

  - `prompt` (string, required)
    The prompt you would like to use to generate the object within the masked region.
Prompt Length Limits: ~90-110 words

  - `refine_prompt` (boolean)
    Controls the automatic prompt refinement feature.
- **`true` (default):** The provided prompt is automatically adjusted for optimal results. The adjusted prompt is then returned in the response payload as `refined_prompt`.
- **`false`:** The original prompt is used as-is, without modification.

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

  - `negative_prompt` (string)
    The prompt you would like to use to specify details or attributes to avoid in the object generated within the masked region.

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

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

  - `webhook_url` (string)
    Optional URL for receiving the result via webhook when the async job completes. See [webhooks](/getting-started/async-requests#webhooks).

  - `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 a response. You can exclude this parameter if you are not interested in recreating your results. This parameter is optional.

  - `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 fields (application/json):

  - `result` (object, required)

  - `result.image_url` (string, required)

  - `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 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)