---
title: "Refine a canvas edge video mask"
method: POST
path: "/v1/collections/{id}/canvases/{canvasId}/edges/{edgeId}/refine-mask"
tags: ["Canvases"]
deprecated: true
---

# Refine a canvas edge video mask

`POST /v1/collections/{id}/canvases/{canvasId}/edges/{edgeId}/refine-mask`

## Request

- Base URL: `https://api.masko.ai`
- URL: `https://api.masko.ai/v1/collections/{id}/canvases/{canvasId}/edges/{edgeId}/refine-mask`
- Auth: HTTP bearer

> **Deprecated.**

Convenience wrapper around `POST /v1/assets/{id}/refine-mask` for a canvas edge. The route resolves the edge `videoAssetId`, refines that video asset mask, and re-exports the active derived formats/sizes. The canvas graph keeps the same raw video asset; desktop playback updates because the active linked WebM/HEVC/stacked variants are replaced underneath it. Any State and reverse edges are rejected because they do not own an independent video asset.

## Path parameters

- `id` string, uuid, required
- `canvasId` string, uuid, required
- `edgeId` string, required

## Headers

- `Idempotency-Key` string

## Request body

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

Canvas edge mask refinement dry-run plan returned

- 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`: Canvas edge 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/84832e255613?raw)