---
title: "Refine a video asset mask"
method: POST
path: "/v1/assets/{id}/refine-mask"
tags: ["Assets"]
---

# Refine a video asset mask

`POST /v1/assets/{id}/refine-mask`

## Request

- Base URL: `https://api.masko.ai`
- URL: `https://api.masko.ai/v1/assets/{id}/refine-mask`
- Auth: HTTP bearer

Refines the active background mask for a completed video asset, then re-exports the requested derived formats and sizes from the refined mask. Omit `formats` and `sizes` to infer the currently active linked variants and refresh all of them. Old matching derived assets are archived and unlinked only after replacement assets are successfully published. Defaults to `dry_run=true` so agents can inspect the exact plan before starting the workflow.

Select Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `api_version` '2026-09-26' | 'legacy'

## Headers

- `Idempotency-Key` string
- `Masko-API-Version` '2026-09-26' | 'legacy'

## Request body

- RefineAssetMaskBody
  - `op` 'add' | 'subtract': Mask operation. add unions the prompted subject into the active mask; subtract removes it from the active mask.
  - `prompt` string, required: Text prompt for the mask region to refine, e.g. "the soccer ball".
  - `model` 'original' | 'pro': Background mask refinement quality. Defaults to pro.
  - `edge_cleanup` object: Optional edge cleanup pass applied to the refined mask.
    - `enabled` boolean
    - `size` integer
  - `formats` string[]: Derived formats to regenerate. Omit to infer the active formats already linked to the video.
  - `sizes` integer[]: Size variants to regenerate. Omit to infer active linked sizes, so all currently used variants are refreshed.
  - `archive_old` boolean: Archive and unlink old matching derived assets after replacement assets are successfully published.
  - `dry_run` boolean: Return the exact refinement/export plan without starting the workflow.

## Response `200`

Mask refinement dry-run plan returned

- union
  - StudioAssetMaskRefinementResponse
    - `data` StudioAssetMaskRefinementData, required
      - `target` 'video_mask_refinement', required
      - `dry_run` boolean, required
      - `video_asset_id` string, uuid, required
      - `bg_job_id` string, required
      - `prompt` string, required
      - `op` 'add' | 'subtract', required
      - `model` 'original' | 'pro', required
      - `edge_cleanup` object
        - `enabled` boolean, required
        - `size` number, required
      - `formats` string[], required
      - `sizes` number[], required
      - `export_count` number, required
      - `archive_old` boolean, required
      - `active_variants` object[], required
        - `id` string, uuid, required
        - `type` string, required
        - `size` number
        - `bgJobId` string
      - `canvas` object
        - `mascot_id` string, uuid
        - `canvasId` string, uuid
        - `edgeId` string
      - `in_flight` object
        - `job_id` string, uuid, required
        - `poll_url` string, required
      - `job_id` string, uuid
      - `poll_url` string
  - AssetMaskRefinementResponse
    - `data` AssetMaskRefinementData, required
      - `target` 'video_mask_refinement', required
      - `dry_run` boolean, required
      - `video_asset_id` string, uuid, required
      - `bg_job_id` string, required
      - `prompt` string, required
      - `op` 'add' | 'subtract', required
      - `model` 'original' | 'pro', required
      - `edge_cleanup` object
        - `enabled` boolean, required
        - `size` number, required
      - `formats` string[], required
      - `sizes` number[], required
      - `export_count` number, required
      - `archive_old` boolean, required
      - `active_variants` object[], required
        - `id` string, uuid, required
        - `type` string, required
        - `size` number
        - `bgJobId` string
      - `canvas` object
        - `collectionId` string, uuid
        - `canvasId` string, uuid
        - `edgeId` string
      - `in_flight` object
        - `job_id` string, uuid, required
        - `poll_url` string, required
      - `job_id` string, uuid
      - `poll_url` string

## Other responses

- `202`: Mask refinement job started
- `400`: Validation error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict

---

[API](https://skmtc.dev/masko/apis/masko-api.md) · [All operations](https://skmtc.dev/masko/apis/masko-api/llms.txt) · [OpenAPI document](https://skmtc.dev/masko/apis/masko-api/revisions/91eb3006a92f?raw)