---
title: "Get Template Detail"
method: GET
path: "/api/hand-templates/{template_id}"
---

# Get Template Detail

`GET /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

Detail payload — base picker fields + cached preprocess artifacts.

Returns 404 on unknown id, or when the template is not visible to
the caller (foreign user's row, or inactive admin row). Mirrors the
visibility rules from `list_visible_templates`.

## Path parameters

- `template_id` string, uuid, 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)