---
title: "Detect hand poses"
method: POST
path: "/v1/apple/hand-pose"
tags: ["Apple"]
---

# Detect hand poses

`POST /v1/apple/hand-pose`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/apple/hand-pose`
- Auth: HTTP bearer

Detects 21 finger joint positions per hand using Apple Vision (Swift-native API).
Joint names use camelCase (wrist, thumbCMC, thumbTip, indexMCP, etc.).
Coordinates are normalized 0–1, top-left origin (y=0 is top of image).

## Request body

- object
  - `image` string, required: Base64-encoded image data (PNG, JPEG, TIFF, HEIC)
  - `max_hands` integer

## Response `200`

Detected hand poses

- object
  - `hands` PoseResult[]
    - `joints` object

## Other responses

- `400`: Invalid request

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)