docs: add representative-face endpoint to 08_media.md

docs_v1.0/API_WORKSPACE/modules/08_media.md

@@ -37,6 +37,61 @@ Stream video with highlights for a specific face trace (follows a single person
 
 ---
 
+### `GET /api/v1/file/:file_uuid/trace/:trace_id/representative-face`
+
+Find the best single face to represent this trace. Uses a two-stage selection: SQL (area × confidence → top 10) then FFmpeg `blurdetect` (sharpness → pick the least blurry).
+
+**Auth**: Required
+**Scope**: file-level
+
+#### Example
+
+```bash
+curl -s "$API/api/v1/file/$FILE_UUID/trace/1939/representative-face" \
+  -H "X-API-Key: $KEY"
+```
+
+#### Response (200)
+
+```json
+{
+  "success": true,
+  "file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
+  "trace_id": 1939,
+  "face_count": 538,
+  "representative": {
+    "frame_number": 68193,
+    "timestamp_secs": 2727.72,
+    "bbox": { "x": 347, "y": 378, "width": 427, "height": 427 },
+    "confidence": 0.760,
+    "quality_score": 138516,
+    "blur_score": 9.46
+  }
+}
+```
+
+#### Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `trace_id` | integer | Face trace ID |
+| `face_count` | integer | Total face detections in this trace |
+| `representative.frame_number` | integer | Frame number of the selected face (primary coordinate) |
+| `representative.timestamp_secs` | float | Time in seconds (derived from `frame_number / fps`) |
+| `representative.bbox` | object | Bounding box `{x, y, width, height}` |
+| `representative.confidence` | float | Detection confidence (0.0–1.0) |
+| `representative.quality_score` | float | Pre-selection score (`area × confidence`) |
+| `representative.blur_score` | float | FFmpeg blurdetect result (lower = sharper) |
+
+#### Error Responses
+
+| HTTP | When |
+|------|------|
+| `404` | File, trace not found, or no suitable face |
+| `500` | FFmpeg or database error |
+
+---
+
 ### `GET /api/v1/file/:file_uuid/video/bbox`
 
 Stream video with bounding box overlay for all detected objects/faces.

docs_v1.0/doc_wasm/modules/08_media.md

@@ -37,6 +37,61 @@ Stream video with highlights for a specific face trace (follows a single person
 
 ---
 
+### `GET /api/v1/file/:file_uuid/trace/:trace_id/representative-face`
+
+Find the best single face to represent this trace. Uses a two-stage selection: SQL (area × confidence → top 10) then FFmpeg `blurdetect` (sharpness → pick the least blurry).
+
+**Auth**: Required
+**Scope**: file-level
+
+#### Example
+
+```bash
+curl -s "$API/api/v1/file/$FILE_UUID/trace/1939/representative-face" \
+  -H "X-API-Key: $KEY"
+```
+
+#### Response (200)
+
+```json
+{
+  "success": true,
+  "file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
+  "trace_id": 1939,
+  "face_count": 538,
+  "representative": {
+    "frame_number": 68193,
+    "timestamp_secs": 2727.72,
+    "bbox": { "x": 347, "y": 378, "width": 427, "height": 427 },
+    "confidence": 0.760,
+    "quality_score": 138516,
+    "blur_score": 9.46
+  }
+}
+```
+
+#### Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `trace_id` | integer | Face trace ID |
+| `face_count` | integer | Total face detections in this trace |
+| `representative.frame_number` | integer | Frame number of the selected face (primary coordinate) |
+| `representative.timestamp_secs` | float | Time in seconds (derived from `frame_number / fps`) |
+| `representative.bbox` | object | Bounding box `{x, y, width, height}` |
+| `representative.confidence` | float | Detection confidence (0.0–1.0) |
+| `representative.quality_score` | float | Pre-selection score (`area × confidence`) |
+| `representative.blur_score` | float | FFmpeg blurdetect result (lower = sharper) |
+
+#### Error Responses
+
+| HTTP | When |
+|------|------|
+| `404` | File, trace not found, or no suitable face |
+| `500` | FFmpeg or database error |
+
+---
+
 ### `GET /api/v1/file/:file_uuid/video/bbox`
 
 Stream video with bounding box overlay for all detected objects/faces.