# Generate All Masks

**Description**
The *Generate All Masks Route* segments an image into every region the model can identify, and returns each region as its own binary mask.
Use it to build a full segmentation map of an image, then feed an individual mask into a mask-based route such as `/erase` or `/gen_fill`.
**Output Characteristics**
- Each mask is returned as a separate PNG at the **same resolution as the input image**, with the region set to **255 (white)** and everything else to **0 (black)**.
- Masks are sorted by `confidence`, best first. `id` is the position in that order, starting at 1.
- `area` is the number of white pixels in the returned mask, measured at the input image's resolution.
- Masks may overlap, and one may contain another — a car and its rear window are returned as two separate masks. The same pixel can belong to several masks.
- Mask URLs are temporary and expire according to your organization's image retention policy. Download or copy any mask you intend to keep.

**Example**
One request returns every region the model finds, each as its own mask. The three below all came from the same call on the image shown.
<table>
<tr>
<th style="text-align: center;">Input Image</th>
<th style="text-align: center;">Mask — road<br><sub>area 7,704,780 · confidence 1.000</sub></th>
<th style="text-align: center;">Mask — car<br><sub>area 1,404,681 · confidence 0.999</sub></th>
<th style="text-align: center;">Mask — person<br><sub>area 358,414 · confidence 0.971</sub></th>
</tr>
<tr>
<td align="center" style="vertical-align: middle;">
<img src="https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/all_masks/street_scene.jpg" width="200" style="border-radius: 8px;">
</td>
<td align="center" style="vertical-align: middle;">
<img src="https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/all_masks/street_scene_mask_road.png" width="200" style="border-radius: 8px;">
</td>
<td align="center" style="vertical-align: middle;">
<img src="https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/all_masks/street_scene_mask_car.png" width="200" style="border-radius: 8px;">
</td>
<td align="center" style="vertical-align: middle;">
<img src="https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/all_masks/street_scene_mask_person.png" width="200" style="border-radius: 8px;">
</td>
</tr>
</table>
This request returned 65 masks. The labels above are ours, added for the example — the API returns no names for a mask, only `id`, `area` and `confidence`. Each pedestrian is a separate mask.
**Choosing a mask**
The model almost always returns one segment covering most or all of the image, and that segment is often ranked first by confidence. A featureless image returns exactly one such mask rather than an empty list.
A mask that covers the entire image cannot be used with `/gen_fill`, which requires a mask containing both black and white pixels and rejects an all-white one. Screening candidates by `area` avoids this.
**Using a mask with /gen_fill and /erase**
Neither `/gen_fill` nor `/erase` generates a mask for you — `mask` is a required parameter on both. A mask always comes from somewhere: a brush stroke drawn by your user, your own pipeline, or this route. Generate one here when you want the model to pick out the regions instead of asking a user to draw them.
`/gen_fill` also accepts a `mask_type` parameter, but it does not change how the mask is interpreted there; it is only meaningful for `/erase`. A mask from this route needs no particular value.
The mask you pass must have the same aspect ratio as the image. Masks from this route come back at the input image's resolution, so they already satisfy that when used with the image they were generated from.
**Choosing between this route and the deprecated v1 route**
New integrations should use this route. The older `/v1/objects/mask_generator` route returns a single ZIP archive of all masks plus a panoptic map, is deprecated, and orders its masks worst-first — the opposite of this route.

Endpoint: POST /all_masks

## Header parameters:

  - `api_token` (string, required)

## 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**.

  - `sync` (boolean)
    Determines whether the request is handled synchronously or asynchronously.
- **`false` (default)** – Returns `202` immediately with a `request_id`. Track it through the [Status Service](https://docs.bria.ai/status).
- **`true`** – Blocks until segmentation completes and returns the masks in the response.

  - `webhook_url` (string)
    Optional URL to receive the result when an asynchronous job completes. See [Webhooks](https://docs.bria.ai/webhooks).
Ignored when `sync` is `true`, since the result is returned on the request itself.

  - `visual_input_content_moderation` (boolean)
    When enabled, the input image is screened before segmentation.
Expected behavior:
- Processing stops if the image fails moderation.
- Returns a `422` error naming the parameter that failed.

The name `content_moderation` is accepted as an alias for backward compatibility with the v1 route.

## Response 200 fields (application/json):

  - `result` (object, required)

  - `result.masks` (array, required)
    Every region the model identified, sorted by confidence, best first. A featureless image returns a single mask covering the whole image rather than an empty array.

  - `result.masks.id` (integer, required)
    Position in the sorted list, starting at 1.
    Example: 1

  - `result.masks.image_url` (string, required)
    Temporary URL of the binary mask PNG, at the input image's resolution. Expires according to your organization's image retention policy.
    Example: https://temp.bria.ai/9c4d61bbc940/25476897e0c146f380a3fdbb944ab18e/a4f.png

  - `result.masks.area` (integer, required)
    Number of white pixels in the returned mask, measured at the input image's resolution.
    Example: 120560

  - `result.masks.confidence` (number, required)
    The model's predicted IoU for this mask, clamped to the range 0 to 1.
    Example: 1

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