--- title: "Generative Fill" method: POST path: "/gen_fill" tags: ["v2 endpoints"] --- # Generative Fill `POST /gen_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 link. **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. ## Headers - `api_token` string, required ## Request body - object - `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, uri — Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/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` 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 Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section. - `400` — Bad request. This can be due to a malformed request, invalid JSON, or a missing required parameter. - `401` — Unauthorized. - `403` — Forbidden. - `404` — Not Found. The requested resource could not be found. This can be due to: - The image or mask URL could not be found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' - `415` — Unsupported media type. - `422` — Unprocessable Entity. This error is returned for validation failures, such as: - A parameter failing content moderation (e.g., `prompt_content_moderation: true` and an unsafe prompt). - Image or mask requirements not being met (e.g., different aspect ratios). - `429` — Request limit exceeded. - `460` — Failed to download image. - `5XX` — **Internal Server Error** – A critical failure occurred in Bria's infrastructure, preventing the Status Service 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). --- [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-service-production.skmtc.workers.dev/v1/apis/bria-ai/image-editing-api-reference/revisions/b69d3f84c7f7/schema)