docs: add co-occur-with endpoint to 08_media.md

2026-05-22 05:35:24 +08:00
parent 2d3017d3c1
commit 6db29fc0e8
3 changed files with 208 additions and 13 deletions
--- a/deliverable_v1.1.0/modules/08_media.md
+++ b/deliverable_v1.1.0/modules/08_media.md
@@ -107,12 +107,77 @@ curl -s "$API/api/v1/file/$FILE_UUID/trace/1939/thumbnail" \
 - **404**: File, trace not found, or no suitable face
 - **500**: FFmpeg or database error

+---
+
+### `GET /api/v1/file/:file_uuid/identities/:identity_uuid_a/co-occur-with/:identity_uuid_b`
+
+Find the first frame where two identities appear together, with representative face thumbnails for both.
+
+**Auth**: Required
+**Scope**: file-level
+
+#### Example
+
+```bash
+# Audrey Hepburn & Cary Grant 第一次同框
+curl -s "$API/api/v1/file/$FILE_UUID/identities/$AUDREY_UUID/co-occur-with/$CARY_UUID" \
+  -H "X-API-Key: $KEY" | jq '{identity_a: .identity_a.name, identity_b: .identity_b.name, first_frame: .first_cooccurrence.frame_number}'
+```
+
+#### Response (200)
+
+```json
+{
+  "success": true,
+  "file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
+  "identity_a": {
+    "identity_uuid": "c3545906-c82d-4b66-aa1d-150bc02decce",
+    "name": "Audrey Hepburn",
+    "trace_id": 920
+  },
+  "identity_b": {
+    "identity_uuid": "2b0ddefe-e2a9-4533-9308-b375594604d5",
+    "name": "Cary Grant",
+    "trace_id": 919
+  },
+  "first_cooccurrence": {
+    "frame_number": 38165,
+    "timestamp_secs": 1526.60,
+    "total_cooccurrence_frames": 3136,
+    "representative_face_a": {
+      "frame_number": 38199,
+      "bbox": { "x": 122, "y": 339, "width": 176, "height": 176 },
+      "confidence": 0.832,
+      "thumbnail_url": "/api/v1/file/aeed71342.../trace/920/thumbnail"
+    },
+    "representative_face_b": {
+      "frame_number": 38291,
+      "bbox": { "x": 511, "y": 315, "width": 192, "height": 192 },
+      "confidence": 0.791,
+      "thumbnail_url": "/api/v1/file/aeed71342.../trace/919/thumbnail"
+    }
+  }
+}
+```
+
+#### Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `identity_a.name` | string | First identity name |
+| `identity_b.name` | string | Second identity name |
+| `first_cooccurrence.frame_number` | int | First frame where both appear |
+| `first_cooccurrence.timestamp_secs` | float | Time in seconds |
+| `first_cooccurrence.total_cooccurrence_frames` | int | Total frames with both present |
+| `first_cooccurrence.representative_face_a/b` | object | Best face thumbnail data for each identity |
+
+#### Error Responses
+
 | HTTP | When |
 |------|------|
-| `404` | File, trace not found, or no suitable face |
-| `500` | FFmpeg or database error |
-
---
+| `404` | File or identity not found |
+| `404` | The two identities never co-occur in this file |
+| `500` | Database or FFmpeg error |

 ### `GET /api/v1/file/:file_uuid/video/bbox`

--- a/docs_v1.0/API_WORKSPACE/modules/08_media.md
+++ b/docs_v1.0/API_WORKSPACE/modules/08_media.md
@@ -107,12 +107,77 @@ curl -s "$API/api/v1/file/$FILE_UUID/trace/1939/thumbnail" \
 - **404**: File, trace not found, or no suitable face
 - **500**: FFmpeg or database error

+---
+
+### `GET /api/v1/file/:file_uuid/identities/:identity_uuid_a/co-occur-with/:identity_uuid_b`
+
+Find the first frame where two identities appear together, with representative face thumbnails for both.
+
+**Auth**: Required
+**Scope**: file-level
+
+#### Example
+
+```bash
+# Audrey Hepburn & Cary Grant 第一次同框
+curl -s "$API/api/v1/file/$FILE_UUID/identities/$AUDREY_UUID/co-occur-with/$CARY_UUID" \
+  -H "X-API-Key: $KEY" | jq '{identity_a: .identity_a.name, identity_b: .identity_b.name, first_frame: .first_cooccurrence.frame_number}'
+```
+
+#### Response (200)
+
+```json
+{
+  "success": true,
+  "file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
+  "identity_a": {
+    "identity_uuid": "c3545906-c82d-4b66-aa1d-150bc02decce",
+    "name": "Audrey Hepburn",
+    "trace_id": 920
+  },
+  "identity_b": {
+    "identity_uuid": "2b0ddefe-e2a9-4533-9308-b375594604d5",
+    "name": "Cary Grant",
+    "trace_id": 919
+  },
+  "first_cooccurrence": {
+    "frame_number": 38165,
+    "timestamp_secs": 1526.60,
+    "total_cooccurrence_frames": 3136,
+    "representative_face_a": {
+      "frame_number": 38199,
+      "bbox": { "x": 122, "y": 339, "width": 176, "height": 176 },
+      "confidence": 0.832,
+      "thumbnail_url": "/api/v1/file/aeed71342.../trace/920/thumbnail"
+    },
+    "representative_face_b": {
+      "frame_number": 38291,
+      "bbox": { "x": 511, "y": 315, "width": 192, "height": 192 },
+      "confidence": 0.791,
+      "thumbnail_url": "/api/v1/file/aeed71342.../trace/919/thumbnail"
+    }
+  }
+}
+```
+
+#### Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `identity_a.name` | string | First identity name |
+| `identity_b.name` | string | Second identity name |
+| `first_cooccurrence.frame_number` | int | First frame where both appear |
+| `first_cooccurrence.timestamp_secs` | float | Time in seconds |
+| `first_cooccurrence.total_cooccurrence_frames` | int | Total frames with both present |
+| `first_cooccurrence.representative_face_a/b` | object | Best face thumbnail data for each identity |
+
+#### Error Responses
+
 | HTTP | When |
 |------|------|
-| `404` | File, trace not found, or no suitable face |
-| `500` | FFmpeg or database error |
-
---
+| `404` | File or identity not found |
+| `404` | The two identities never co-occur in this file |
+| `500` | Database or FFmpeg error |

 ### `GET /api/v1/file/:file_uuid/video/bbox`

--- a/docs_v1.0/doc_wasm/modules/08_media.md
+++ b/docs_v1.0/doc_wasm/modules/08_media.md
@@ -85,11 +85,6 @@ curl -s "$API/api/v1/file/$FILE_UUID/trace/1939/representative-face" \

 #### Error Responses

-| HTTP | When |
-|------|------|
-| `404` | File, trace not found, or no suitable face |
-| `500` | FFmpeg or database error |
-
 ---

 ### `GET /api/v1/file/:file_uuid/trace/:trace_id/thumbnail`
@@ -114,6 +109,76 @@ curl -s "$API/api/v1/file/$FILE_UUID/trace/1939/thumbnail" \

 ---

+### `GET /api/v1/file/:file_uuid/identities/:identity_uuid_a/co-occur-with/:identity_uuid_b`
+
+Find the first frame where two identities appear together, with representative face thumbnails for both.
+
+**Auth**: Required
+**Scope**: file-level
+
+#### Example
+
+```bash
+# Audrey Hepburn & Cary Grant 第一次同框
+curl -s "$API/api/v1/file/$FILE_UUID/identities/$AUDREY_UUID/co-occur-with/$CARY_UUID" \
+  -H "X-API-Key: $KEY" | jq '{identity_a: .identity_a.name, identity_b: .identity_b.name, first_frame: .first_cooccurrence.frame_number}'
+```
+
+#### Response (200)
+
+```json
+{
+  "success": true,
+  "file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
+  "identity_a": {
+    "identity_uuid": "c3545906-c82d-4b66-aa1d-150bc02decce",
+    "name": "Audrey Hepburn",
+    "trace_id": 920
+  },
+  "identity_b": {
+    "identity_uuid": "2b0ddefe-e2a9-4533-9308-b375594604d5",
+    "name": "Cary Grant",
+    "trace_id": 919
+  },
+  "first_cooccurrence": {
+    "frame_number": 38165,
+    "timestamp_secs": 1526.60,
+    "total_cooccurrence_frames": 3136,
+    "representative_face_a": {
+      "frame_number": 38199,
+      "bbox": { "x": 122, "y": 339, "width": 176, "height": 176 },
+      "confidence": 0.832,
+      "thumbnail_url": "/api/v1/file/aeed71342.../trace/920/thumbnail"
+    },
+    "representative_face_b": {
+      "frame_number": 38291,
+      "bbox": { "x": 511, "y": 315, "width": 192, "height": 192 },
+      "confidence": 0.791,
+      "thumbnail_url": "/api/v1/file/aeed71342.../trace/919/thumbnail"
+    }
+  }
+}
+```
+
+#### Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `identity_a.name` | string | First identity name |
+| `identity_b.name` | string | Second identity name |
+| `first_cooccurrence.frame_number` | int | First frame where both appear |
+| `first_cooccurrence.timestamp_secs` | float | Time in seconds |
+| `first_cooccurrence.total_cooccurrence_frames` | int | Total frames with both present |
+| `first_cooccurrence.representative_face_a/b` | object | Best face thumbnail data for each identity |
+
+#### Error Responses
+
+| HTTP | When |
+|------|------|
+| `404` | File or identity not found |
+| `404` | The two identities never co-occur in this file |
+| `500` | Database or FFmpeg error |
+
 ### `GET /api/v1/file/:file_uuid/video/bbox`

 Stream video with bounding box overlay for all detected objects/faces.