Skip to content

Pose & Appearance API

Pose & Appearance

Endpoints for retrieving pose keypoints and appearance color data for face detail modal display.

GET /api/v1/file/:file_uuid/pose

Auth: Required Scope: file-level

Get pose keypoints for a specific frame. Returns 17 COCO keypoints with deduplication (highest confidence selected for each keypoint name).

Path Parameters

Field Type Required Description
file_uuid string Yes File UUID

Query Parameters

Field Type Required Description
frame integer Yes Frame number

Example

curl -s "$API/api/v1/file/$FILE_UUID/pose?frame=303" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "frame": 303,
  "keypoints": [
    {"name": "nose", "x": 315.91, "y": 364.25, "confidence": 0.616},
    {"name": "left_eye", "x": 312.45, "y": 362.80, "confidence": 0.616},
    {"name": "right_eye", "x": 316.21, "y": 361.38, "confidence": 0.616},
    {"name": "left_ear", "x": 0.0, "y": 0.0, "confidence": 0.0},
    {"name": "right_ear", "x": 0.0, "y": 0.0, "confidence": 0.0},
    {"name": "left_shoulder", "x": 0.0, "y": 0.0, "confidence": 0.0},
    {"name": "right_shoulder", "x": 0.0, "y": 0.0, "confidence": 0.0},
    {"name": "left_elbow", "x": 0.0, "y": 0.0, "confidence": 0.0},
    {"name": "right_elbow", "x": 0.0, "y": 0.0, "confidence": 0.0},
    {"name": "left_wrist", "x": 0.0, "y": 0.0, "confidence": 0.0},
    {"name": "right_wrist", "x": 0.0, "y": 0.0, "confidence": 0.0},
    {"name": "left_hip", "x": 0.0, "y": 0.0, "confidence": 0.0},
    {"name": "right_hip", "x": 0.0, "y": 0.0, "confidence": 0.0},
    {"name": "left_knee", "x": 0.0, "y": 0.0, "confidence": 0.0},
    {"name": "right_knee", "x": 0.0, "y": 0.0, "confidence": 0.0},
    {"name": "left_ankle", "x": 0.0, "y": 0.0, "confidence": 0.0},
    {"name": "right_ankle", "x": 0.0, "y": 0.0, "confidence": 0.0}
  ],
  "pose_class": "unknown",
  "confidence": null
}
Field Type Description
frame integer Frame number
keypoints array 17 COCO keypoints (deduplicated)
keypoints[].name string Keypoint name
keypoints[].x float X coordinate in pixels
keypoints[].y float Y coordinate in pixels
keypoints[].confidence float Detection confidence 0-1 (0 means not detected)
pose_class string Always "unknown" in POC
confidence null Always null in POC

COCO-17 Keypoint Names

nose, left_eye, right_eye, left_ear, right_ear,
left_shoulder, right_shoulder, left_elbow, right_elbow,
left_wrist, right_wrist, left_hip, right_hip,
left_knee, right_knee, left_ankle, right_ankle

Error Responses

HTTP When
404 Frame not found or pose.json not found
401 Missing or invalid API key

GET /api/v1/file/:file_uuid/appearance

Auth: Required Scope: file-level

Get appearance color data for a specific frame. Returns HSV histogram for color analysis.

Path Parameters

Field Type Required Description
file_uuid string Yes File UUID

Query Parameters

Field Type Required Description
frame integer Yes Frame number

Example

curl -s "$API/api/v1/file/$FILE_UUID/appearance?frame=303" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "frame": 303,
  "dominant_colors": [],
  "hsv_histogram": [
    [0.59, 0.0, 0.0, ...],
    [0.97, 0.02, 0.01, ...],
    [0.004, 0.02, 0.03, ...]
  ]
}
Field Type Description
frame integer Frame number
dominant_colors array Empty array in POC ([])
hsv_histogram array 3x30 HSV histogram bins (H, S, V channels)

Error Responses

HTTP When
404 Frame not found or appearance.json not found
401 Missing or invalid API key

Data Source

Processor File Location
Pose {file_uuid}.pose.json {OUTPUT_DIR}/
Appearance {file_uuid}.appearance.json {OUTPUT_DIR}/

POC Limitations

Feature POC Status Future
Pose classification "unknown" ML model for standing/sitting/etc.
Dominant colors Empty array [] HSV extraction algorithm
Multiple persons First person only Match by trace_id
Confidence null Aggregated confidence score

Updated: 2026-07-19 — New pose and appearance endpoints for face detail display

Version History

Version Date Changes
1.0 2026-10-24 Initial documentation