---
title: "Generate Mask by Key Points"
method: POST
path: "/mask_by_key_points"
tags: ["Masking Endpoints"]
---

# Generate Mask by Key Points

`POST /mask_by_key_points`

Generates a segmentation mask video based on coordinate key points.

Response behavior:
- Returns HTTP 202 with `request_id` and `status_url`
- The final result (via Status Service) will contain a `mask_url`.

Constraints:
- Max Duration: 5 seconds (Truncated if `auto_trim`=true).
- Max Resolution: 750p.

## Headers

- `api_token` string, required

## Request body

- object
  - `video` string, required — Publicly accessible URL for the input video file.
  - `frame_index` integer — The frame number to apply key points to.
  - `key_points` object[], required — An array of coordinate objects defining the mask hints. - **positive**: Inclusion points. These coordinates identify areas that SHOULD be part of the mask. - **negative**: Exclusion points. These coordinates identify areas that SHOULD NOT be part of the mask.
    - `x` integer
    - `y` integer
    - `type` 'positive' | 'negative'
  - `auto_trim` boolean — If true, trims the video to the 5s limit.
  - `output_container_and_codec` 'mp4_h264' | 'mp4_h265' | 'webm_vp9' | 'mov_h265' | 'mov_proresks' | 'mkv_h264' | 'mkv_h265' | 'mkv_vp9' | 'gif'
  - `webhook_url` string, uri — Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks).

## Response `202`

Accepted

- AsyncInitialResponse
  - `request_id` string, required
  - `status_url` string, required

## Other responses

- `400` — Bad request
- `403` — Forbidden
- `405` — Method not allowed
- `415` — Unsupported input container or codec
- `422` — Unprocessable entity
- `429` — Too many requests
- `500` — Internal server error

---

[API](https://skmtc.net/bria-ai/apis/video-api-reference.md) · [All operations](https://skmtc.net/bria-ai/apis/video-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bria-ai/video-api-reference/revisions/fa6d2efc9689/schema)