---
title: "Annotate Template"
method: POST
path: "/api/hand-templates/annotate"
---

# Annotate Template

`POST /api/hand-templates/annotate`

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

Suggest pose / skin / aspect / background for an uploaded hand
photo. Used by the upload modal to auto-fill the form so the user
typically only needs to confirm + click Save.

The endpoint is **best-effort**: Gemini outages don't 5xx — the
annotator falls back to the form defaults (single_hand / light /
1:1 / white) so the upload still works. Confidence rides in the
response so the UI can dim low-confidence suggestions.

Latency: 1-3s typical (Gemini Pro Vision on a single 4K-or-smaller
image), 30s ceiling via the genai HTTP timeout.

## Request body

- HandTemplateAnnotateRequest: Body for `POST /api/hand-templates/annotate`. Caller uploaded a hand photo via /api/uploads/standalone-presign; this asks the server to suggest pose / skin / aspect / background values for the upload form. The frontend pre-fills the form with the suggestions but the user can still override before saving. Supplies the raw `hand_s3_key` (validated to the caller's prefix) plus an optional `content_type`.
  - `hand_s3_key` string, nullable
  - `content_type` string, nullable

## Response `200`

Successful Response

- HandTemplateAnnotateResponse: Suggested discriminator values for an uploaded hand photo. ``confidence`` is the LLM's self-reported confidence (0–1). A low value doesn't gate anything in v1 — the UI can dim the suggestion chip or surface a tooltip explaining the user should review.
  - `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
  - `confidence` number, required

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