---
title: "Update Template Masks"
method: PATCH
path: "/api/hand-templates/{template_id}/masks"
---

# Update Template Masks

`PATCH /api/hand-templates/{template_id}/masks`

## Request

- Base URL: `https://api.tintin-x.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tintin-x.com/api/hand-templates/{template_id}/masks`
- Auth: HTTP bearer

Overwrite cached SAM3 masks with user-tuned versions from the
mask editor.

Same access rules as the assignments editor (`PATCH .../assignments`)
— non-admin templates only, must have a populated preprocess cache.

On success: uploads each submitted mask PNG, recomputes
`mask_centroids`, auto-removes any `(hand, finger)` assignment whose
target mask got fully erased, and re-renders `labeled_overlay` +
`assignment_viz` against the (possibly trimmed) `assigned` dict.

## Path parameters

- `template_id` string, uuid, required

## Request body

- HandTemplateMasksUpdate: Body of `PATCH /api/hand-templates/{id}/masks` — overwrites a subset of the cached SAM3 masks with hand-tuned versions from the mask editor. Each `mask_id` must be unique and in `[0, N)` where N is the count of cached masks; un-submitted entries keep their existing bytes.
  - `masks` HandTemplateMaskEntry[], required
    - `mask_id` integer, required
    - `png_base64` string, required

## Response `200`

Successful Response

- HandTemplateDetailResponse: Single-template detail payload — extends the picker shape with the per-template preprocess cache. Returned by `GET /api/hand-templates/{id}`.
  - `id` string, uuid, required
  - `slug` string, required
  - `label` string, required
  - `pose` 'single_hand' | 'two_hands_layered' | 'fist_flat_dual' | 'holding_prop', required
  - `skin_tone` 'fair' | 'light' | 'medium' | 'tan' | 'deep', required
  - `aspect_ratio` '1:1' | '4:5' | '3:4' | '16:9', required
  - `background` 'white' | 'gradient' | 'extended', required
  - `prop_slug` string, nullable
  - `hand_url` string, required
  - `preview_url` string, nullable
  - `source` 'admin' | 'upload' | 'ai_gen', required
  - `is_active` boolean, required
  - `gen_prompt` string, nullable
  - `owner_user_id` string, uuid, nullable
  - `preprocess_ready` boolean
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `stage_status` object
  - `hand_preprocess` HandPreprocessArtifacts: Presigned URLs + parsed JSON for the per-template hand-preprocess cache populated by the worker. Surfaces in `GET /api/hand-templates/{id}`. The worker writes these artifacts under `apps/nail-art/templates/{template_id}/preprocess/` after the first try-on consumes a template; subsequent try-ons hit the cache and skip the SAM3 + VLM steps that produced them.
    - `bare` string, nullable
    - `sam3_masks` string[]
    - `labeled_overlay` string, nullable
    - `label_viz` string, nullable
    - `assignment_viz` string, nullable
    - `mask_centroids` array[], nullable
      - number[], nullable
    - `label_response` object, nullable
    - `fingertip_bboxes_viz` string, nullable
    - `assignments` object, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/tintin-x/apis/tintin-api.md) · [All operations](https://skmtc.dev/tintin-x/apis/tintin-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tintin-x/apis/tintin-api/revisions/8839a8d0a66c?raw)