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

# Update Template Metadata

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

## 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}`
- Auth: HTTP bearer

Edit pose / skin_tone on a user-owned template.

The auto-annotator misses occasionally; users surface the wrong
pose or skin tone in the detail view and want to fix it without
re-uploading. Aspect / background / source are intentionally not
editable: aspect was baked into the source image dims at upload
time, background is unused by the runtime, and source is system-
managed.

Same auth contract as the assignments editor — admin rows are
read-only catalog entries; only the owner of a user/ai_gen row
can mutate it.

## Path parameters

- `template_id` string, uuid, required

## Request body

- HandTemplateMetadataUpdate: Body for `PATCH /api/hand-templates/{id}`. Lets the user fix pose / skin-tone on their own templates after upload — the auto-annotation occasionally guesses wrong, and the values feed downstream prompt composition. Both fields are optional: only present keys are written. Aspect ratio / background / source are intentionally not editable here (aspect feeds image dims that were already baked at upload time).
  - `pose` 'single_hand' | 'two_hands_layered' | 'fist_flat_dual' | 'holding_prop', nullable
  - `skin_tone` 'fair' | 'light' | 'medium' | 'tan' | 'deep', nullable

## 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)