Assets

Refine a video asset mask

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.

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

Path parameters

idstring uuid required

Query parameters

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

Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree.

Headers

Idempotency-Keystring

Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.

Masko-API-Version'2026-09-26' | 'legacy'

Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract.

Request body

op'add' | 'subtract'

Mask operation. add unions the prompted subject into the active mask; subtract removes it from the active mask.

promptstring required

Text prompt for the mask region to refine, e.g. "the soccer ball".

model'original' | 'pro'

Background mask refinement quality. Defaults to pro.

formatsstring[]

Derived formats to regenerate. Omit to infer the active formats already linked to the video.

sizesinteger[]

Size variants to regenerate. Omit to infer active linked sizes, so all currently used variants are refreshed.

archive_oldboolean

Archive and unlink old matching derived assets after replacement assets are successfully published.

dry_runboolean

Return the exact refinement/export plan without starting the workflow.

Response

Mask refinement dry-run plan returned

OR

Changes

No recorded changes to this operation across all 1 revision of this API.