From 7a193845bb64507129f133a1fc96bceb1f70d4a7 Mon Sep 17 00:00:00 2001 From: Warren Date: Fri, 8 May 2026 04:25:15 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20remove=20.rs=20annotations,=20fix=20:uu?= =?UTF-8?q?id=E2=86=92:file=5Fuuid,=20:id=E2=86=92:trace=5Fid?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs_v1.0/API_V1.0.0/API_DICTIONARY_V1.0.0.md | 30 +-- .../RELEASE/RELEASE_API_REFERENCE_v1.0.0.md | 215 ++++++++---------- 2 files changed, 105 insertions(+), 140 deletions(-) diff --git a/docs_v1.0/API_V1.0.0/API_DICTIONARY_V1.0.0.md b/docs_v1.0/API_V1.0.0/API_DICTIONARY_V1.0.0.md index e1a735a..1ef3314 100644 --- a/docs_v1.0/API_V1.0.0/API_DICTIONARY_V1.0.0.md +++ b/docs_v1.0/API_V1.0.0/API_DICTIONARY_V1.0.0.md @@ -27,7 +27,7 @@ | 11 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata | | 12 | POST | `/api/v1/file/:file_uuid/process` | Start processing pipeline | | 13 | GET | `/api/v1/file/:file_uuid/chunks` | List pre-chunks for file | -| 14 | GET | `/api/v1/progress/:uuid` | Processing progress | +| 14 | GET | `/api/v1/progress/:file_uuid` | Processing progress | | 15 | GET | `/api/v1/jobs` | List monitor jobs (filterable by status) | | 16 | POST | `/api/v1/config/cache` | Toggle Redis cache | | 17 | POST | `/api/v1/search/visual` | Search visual chunks | @@ -45,10 +45,10 @@ | 24 | GET | `/api/v1/file/:file_uuid/identities` | Identities in this file | | 25 | GET | `/api/v1/identities` | List all identities | | 26 | POST | `/api/v1/identity` | Register new identity | -| 27 | GET | `/api/v1/identity/:uuid` | Identity detail | -| 28 | DELETE | `/api/v1/identity/:uuid` | Delete identity | -| 29 | GET | `/api/v1/identity/:uuid/files` | Files for an identity | -| 30 | GET | `/api/v1/identity/:uuid/chunks` | Chunks for an identity | +| 27 | GET | `/api/v1/identity/:identity_uuid` | Identity detail | +| 28 | DELETE | `/api/v1/identity/:identity_uuid` | Delete identity | +| 29 | GET | `/api/v1/identity/:identity_uuid/files` | Files for an identity | +| 30 | GET | `/api/v1/identity/:identity_uuid/chunks` | Chunks for an identity | | 31 | POST | `/api/v1/resource/register` | Register processing resource | | 32 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat | | 33 | GET | `/api/v1/resources` | List all resources | @@ -57,9 +57,9 @@ | # | Method | Route | Description | |---|--------|-------|-------------| -| 34 | POST | `/api/v1/identity/:uuid/bind` | Bind face → identity | -| 35 | POST | `/api/v1/identity/:uuid/unbind` | Unbind face from identity | -| 36 | POST | `/api/v1/identity/:from/mergeinto` | Merge identities | +| 34 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity | +| 35 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity | +| 36 | POST | `/api/v1/identity/:from_uuid/mergeinto` | Merge identities | ## Face Candidates (identities.rs) @@ -79,23 +79,23 @@ | # | Method | Route | Description | |---|--------|-------|-------------| -| 41 | POST | `/api/v1/file/:uuid/face_trace/sortby` | List traces (sorted/filtered) | -| 42 | GET | `/api/v1/file/:uuid/trace/:id/faces` | Single trace detections + interpolation | +| 41 | POST | `/api/v1/file/:file_uuid/face_trace/sortby` | List traces (sorted/filtered) | +| 42 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/faces` | Single trace detections + interpolation | ## Media (media_api.rs) | # | Method | Route | Description | |---|--------|-------|-------------| -| 43 | GET | `/api/v1/file/:uuid/thumbnail` | Frame JPEG (optional crop via `?frame=&x=&y=&w=&h=`) | -| 44 | GET | `/api/v1/file/:uuid/video` | Raw video stream (`?start=&end=` for range) | -| 45 | GET | `/api/v1/file/:uuid/video/bbox` | Bbox overlay video (`?start=&end=&duration=`) | -| 46 | GET | `/api/v1/file/:uuid/trace/:id/video` | Trace clip with bbox overlay (`?padding=`) | +| 43 | GET | `/api/v1/file/:file_uuid/thumbnail` | Frame JPEG (optional crop via `?frame=&x=&y=&w=&h=`) | +| 44 | GET | `/api/v1/file/:file_uuid/video` | Raw video stream (`?start=&end=` for range) | +| 45 | GET | `/api/v1/file/:file_uuid/video/bbox` | Bbox overlay video (`?start=&end=&duration=`) | +| 46 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | Trace clip with bbox overlay (`?padding=`) | ## Identity Delete | # | Method | Route | Description | |---|--------|-------|-------------| -| 47 | DELETE | `/api/v1/identity/:uuid` | Delete identity + unbind all faces | +| 47 | DELETE | `/api/v1/identity/:identity_uuid` | Delete identity + unbind all faces | ## Agents (agent_api.rs + five_w1h_agent_api.rs + identity_agent_api.rs) diff --git a/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_v1.0.0.md b/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_v1.0.0.md index c57515c..fd27533 100644 --- a/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_v1.0.0.md +++ b/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_v1.0.0.md @@ -20,83 +20,73 @@ owner: "Warren" | Development | `http://localhost:3003` | | Auth | Header `X-API-Key: ` (login endpoint unprotected) | -## 1. System (server.rs) +## 1. System -| # | Method | Path | Description | File:Line | -|---|--------|------|-------------|-----------| -| 1 | GET | `/health` | Server status (ok/degraded) | `server.rs:2529` | -| 2 | GET | `/health/detailed` | Per-service health + latency | `server.rs:2530` | -| 3 | POST | `/api/v1/auth/login` | Username/password → API key | `server.rs:2531` | -| 4 | POST | `/api/v1/auth/logout` | Invalidate session | `server.rs:2532` | -| 5 | GET | `/api/v1/stats/ingest` | Ingest statistics | `server.rs:2533` | -| 6 | GET | `/api/v1/stats/sftpgo` | SFTPGo status | `server.rs:2534` | -| 7 | GET | `/api/v1/stats/inference` | LLM/Embedding health | `server.rs:2535` | -| 8 | POST | `/api/v1/config/cache` | Toggle Redis cache | `server.rs:2513` | +| # | Method | Path | Description | +|---|--------|------|-------------| +| 1 | GET | `/health` | Server status (ok/degraded) | +| 2 | GET | `/health/detailed` | Per-service health + latency | +| 3 | POST | `/api/v1/auth/login` | Username/password → API key | +| 4 | POST | `/api/v1/auth/logout` | Invalidate session | +| 5 | GET | `/api/v1/stats/ingest` | Ingest statistics | +| 6 | GET | `/api/v1/stats/sftpgo` | SFTPGo status | +| 7 | GET | `/api/v1/stats/inference` | LLM/Embedding health | +| 8 | POST | `/api/v1/config/cache` | Toggle Redis cache | **Example:** ```bash GET /health → {"status":"ok","version":"1.0.0","uptime_ms":248233} - -GET /health/detailed -→ {"status":"ok","services":{"postgres":{"status":"ok","latency_ms":3}},...} ``` -## 2. File Management (server.rs) +## 2. File Management -| # | Method | Path | Description | File:Line | -|---|--------|------|-------------|-----------| -| 9 | POST | `/api/v1/files/register` | Register video → UUID | `server.rs:2505` | -| 10 | POST | `/api/v1/unregister` | Delete file + all data | `server.rs:2506` | -| 11 | GET | `/api/v1/files/scan` | Scan directory for new files | `server.rs:2507` | -| 12 | GET | `/api/v1/file/:file_uuid` | Single file detail | `identity_api.rs:16` | -| 13 | GET | `/api/v1/files` | List files (paginated) | `identity_api.rs:15` | -| 14 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata | `server.rs:2508` | -| 15 | POST | `/api/v1/file/:file_uuid/process` | Start pipeline | `server.rs:2509` | -| 16 | GET | `/api/v1/file/:file_uuid/chunks` | List pre-chunks | `server.rs:2510` | -| 17 | GET | `/api/v1/progress/:uuid` | Processing progress | `server.rs:2511` | -| 18 | GET | `/api/v1/jobs` | Monitor jobs (filterable) | `server.rs:2512` | +| # | Method | Path | Description | +|---|--------|------|-------------| +| 9 | POST | `/api/v1/files/register` | Register video → file_uuid | +| 10 | POST | `/api/v1/unregister` | Delete file + all data | +| 11 | GET | `/api/v1/files/scan` | Scan directory for new files | +| 12 | GET | `/api/v1/files` | List files (paginated) | +| 13 | GET | `/api/v1/file/:file_uuid` | Single file detail | +| 14 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata | +| 15 | POST | `/api/v1/file/:file_uuid/process` | Start pipeline | +| 16 | GET | `/api/v1/file/:file_uuid/chunks` | List pre-chunks | +| 17 | GET | `/api/v1/progress/:file_uuid` | Processing progress | +| 18 | GET | `/api/v1/jobs` | Monitor jobs (filterable) | **Example:** ```bash POST /api/v1/files/register {"file_path":"/sftpgo/data/demo/video.mp4"} -→ {"success":true,"file_uuid":"3abeee81...","duration":5954.0,...} - -GET /api/v1/files?page=1&page_size=5 -→ {"files":[...],"total":37,"page":1} +→ {"success":true,"file_uuid":"3abeee81...","duration":5954.0} ``` -## 3. Search (server.rs + search.rs + universal_search.rs) +## 3. Search -| # | Method | Path | Description | File:Line | -|---|--------|------|-------------|-----------| -| 19 | POST | `/api/v1/search/visual` | Visual chunk search | `server.rs:2536` | -| 20 | POST | `/api/v1/search/visual/class` | By object class | `server.rs:2541` | -| 21 | POST | `/api/v1/search/visual/density` | By spatial density | `server.rs:2546` | -| 22 | POST | `/api/v1/search/visual/combination` | Combined visual search | `server.rs:2541` | -| 23 | POST | `/api/v1/search/visual/stats` | Visual stats | `server.rs:2545` | -| 24 | POST | `/api/v1/search/smart` | Semantic (EmbeddingGemma + pgvector) | `search.rs:164` | -| 25 | POST | `/api/v1/search/universal` | BM25 keyword (requires uuid) | `universal_search.rs:94` | -| 26 | POST | `/api/v1/search/frames` | Frame-level search | `universal_search.rs:95` | +| # | Method | Path | Description | +|---|--------|------|-------------| +| 19 | POST | `/api/v1/search/visual` | Visual chunk search | +| 20 | POST | `/api/v1/search/visual/class` | By object class | +| 21 | POST | `/api/v1/search/visual/density` | By spatial density | +| 22 | POST | `/api/v1/search/visual/combination` | Combined visual search | +| 23 | POST | `/api/v1/search/visual/stats` | Visual stats | +| 24 | POST | `/api/v1/search/smart` | Semantic (EmbeddingGemma + pgvector) | +| 25 | POST | `/api/v1/search/universal` | BM25 keyword (requires file_uuid) | +| 26 | POST | `/api/v1/search/frames` | Frame-level search | **Example:** ```bash POST /api/v1/search/universal -{"query":"friends","mode":"bm25","uuid":"3abeee81..."} -→ {"count":1,"results":[{"text":"You won't find it difficult to make some new friends.",...}]} - -POST /api/v1/search/smart -{"query":"Audrey Hepburn","uuid":"3abeee81..."} -→ {"strategy":"semantic_vector_search","results":[...]} +{"query":"friends","mode":"bm25","file_uuid":"3abeee81..."} +→ {"count":1,"results":[{"text":"You won't find it difficult..."}]} ``` -## 4. Face Trace (trace_agent_api.rs) +## 4. Face Trace -| # | Method | Path | Description | File:Line | -|---|--------|------|-------------|-----------| -| 27 | POST | `/api/v1/file/:uuid/face_trace/sortby` | List traces (sorted/filtered) | `trace_agent_api.rs:14` | -| 28 | GET | `/api/v1/file/:uuid/trace/:id/faces` | Trace detections (+ interpolation) | `trace_agent_api.rs:18` | +| # | Method | Path | Description | +|---|--------|------|-------------| +| 27 | POST | `/api/v1/file/:file_uuid/face_trace/sortby` | List traces (sorted/filtered) | +| 28 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/faces` | Trace detections (+ interpolation) | **Parameters:** - `sort_by`: `face_count` | `duration` | `first_appearance` @@ -108,53 +98,44 @@ POST /api/v1/search/smart POST /api/v1/file/3abeee81.../face_trace/sortby {"sort_by":"face_count","limit":3} → {"total_traces":6892,"total_faces":108204, - "traces":[{"trace_id":3128,"face_count":1109,...}]} - -GET /api/v1/file/3abeee81.../trace/2/faces?limit=3&interpolate=true -→ {"faces":[{"start_frame":4620,"interpolated":false,...}]} + "traces":[{"trace_id":3128,"face_count":1109}]} ``` -## 5. Media (media_api.rs) +## 5. Media -| # | Method | Path | Description | File:Line | -|---|--------|------|-------------|-----------| -| 29 | GET | `/api/v1/file/:uuid/thumbnail` | Frame JPEG (optional crop) | `media_api.rs:23` | -| 30 | GET | `/api/v1/file/:uuid/video` | Raw video stream | `media_api.rs:18` | -| 31 | GET | `/api/v1/file/:uuid/video/bbox` | Bbox overlay video | `media_api.rs:14` | -| 32 | GET | `/api/v1/file/:uuid/trace/:id/video` | Trace clip with bbox | `media_api.rs:22` | +| # | Method | Path | Description | +|---|--------|------|-------------| +| 29 | GET | `/api/v1/file/:file_uuid/thumbnail` | Frame JPEG (?frame=&x=&y=&w=&h=) | +| 30 | GET | `/api/v1/file/:file_uuid/video` | Raw video stream (?start=&end=) | +| 31 | GET | `/api/v1/file/:file_uuid/video/bbox` | Bbox overlay (?start=&end=&duration=) | +| 32 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | Trace clip (?padding=) | -**Parameters:** -- `thumbnail`: `?frame=4650&x=0&y=0&w=100&h=100` -- `video`: `?start=0&end=300` (seconds) -- `video/bbox`: `?start=0&end=300&duration=10` -- `trace/:id/video`: `?padding=2.0` +## 6. Identities -## 6. Identities (identity_api.rs + identities.rs) - -| # | Method | Path | Description | File:Line | -|---|--------|------|-------------|-----------| -| 33 | GET | `/api/v1/identities` | List all identities | `identity_api.rs:17` | -| 34 | GET | `/api/v1/file/:uuid/identities` | Identities in a file | `identity_api.rs:21` | -| 35 | POST | `/api/v1/identity` | Register new identity | `identities.rs:34` | -| 36 | GET | `/api/v1/identity/:uuid` | Identity detail | `identity_api.rs:25` | -| 37 | DELETE | `/api/v1/identity/:uuid` | Delete identity | `identity_api.rs:29` | -| 38 | GET | `/api/v1/identity/:uuid/files` | Files for identity | `identity_api.rs:33` | -| 39 | GET | `/api/v1/identity/:uuid/chunks` | Chunks for identity | `identity_api.rs:34` | -| 40 | GET | `/api/v1/faces/candidates` | Unbound face gallery | `identities.rs:35` | +| # | Method | Path | Description | +|---|--------|------|-------------| +| 33 | GET | `/api/v1/identities` | List all identities | +| 34 | GET | `/api/v1/file/:file_uuid/identities` | Identities in a file | +| 35 | POST | `/api/v1/identity` | Register new identity | +| 36 | GET | `/api/v1/identity/:identity_uuid` | Identity detail | +| 37 | DELETE | `/api/v1/identity/:identity_uuid` | Delete identity | +| 38 | GET | `/api/v1/identity/:identity_uuid/files` | Files for identity | +| 39 | GET | `/api/v1/identity/:identity_uuid/chunks` | Chunks for identity | +| 40 | GET | `/api/v1/faces/candidates` | Unbound face gallery | **Example:** ```bash GET /api/v1/identities?page=1&page_size=5 -→ {"identities":[{"name":"Cary Grant","tmdb_id":...,}],...} +→ {"identities":[{"name":"Cary Grant","tmdb_id":...}]} ``` -## 7. Identity Binding (identity_binding.rs) +## 7. Identity Binding -| # | Method | Path | Description | File:Line | -|---|--------|------|-------------|-----------| -| 41 | POST | `/api/v1/identity/:uuid/bind` | Bind face → identity | `identity_binding.rs:291` | -| 42 | POST | `/api/v1/identity/:uuid/unbind` | Unbind face from identity | `identity_binding.rs:292` | -| 43 | POST | `/api/v1/identity/:from/mergeinto` | Merge two identities | `identity_binding.rs:296` | +| # | Method | Path | Description | +|---|--------|------|-------------| +| 41 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity | +| 42 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity | +| 43 | POST | `/api/v1/identity/:from_uuid/mergeinto` | Merge two identities | **Example:** ```bash @@ -163,51 +144,35 @@ POST /api/v1/identity/a9a90105.../bind → {"success":true} ``` -## 8. Resources (identity_api.rs) +## 8. Resources -| # | Method | Path | Description | File:Line | -|---|--------|------|-------------|-----------| -| 44 | POST | `/api/v1/resource/register` | Register processing resource | `identity_api.rs:35` | -| 45 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat | `identity_api.rs:34` | -| 46 | GET | `/api/v1/resources` | List all resources | `identity_api.rs:33` | +| # | Method | Path | Description | +|---|--------|------|-------------| +| 44 | POST | `/api/v1/resource/register` | Register processing resource | +| 45 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat | +| 46 | GET | `/api/v1/resources` | List all resources | -## 9. Agents — 5W1H (five_w1h_agent_api.rs) +## 9. Agents — 5W1H -| # | Method | Path | Description | File:Line | -|---|--------|------|-------------|-----------| -| 47 | POST | `/api/v1/agents/translate` | AI text translation | `agent_api.rs:8` | -| 48 | POST | `/api/v1/agents/5w1h/analyze` | Single chunk analysis | `five_w1h_agent_api.rs:20` | -| 49 | POST | `/api/v1/agents/5w1h/batch` | Batch analysis | `five_w1h_agent_api.rs:21` | -| 50 | GET | `/api/v1/agents/5w1h/status` | Job status | `five_w1h_agent_api.rs:22` | +| # | Method | Path | Description | +|---|--------|------|-------------| +| 47 | POST | `/api/v1/agents/translate` | AI text translation | +| 48 | POST | `/api/v1/agents/5w1h/analyze` | Single chunk analysis | +| 49 | POST | `/api/v1/agents/5w1h/batch` | Batch analysis | +| 50 | GET | `/api/v1/agents/5w1h/status` | Job status | -## 10. Agents — Identity (identity_agent_api.rs) +## 10. Agents — Identity -| # | Method | Path | Description | File:Line | -|---|--------|------|-------------|-----------| -| 51 | POST | `/api/v1/agents/identity/analyze` | Identify faces in file | `identity_agent_api.rs:17` | -| 52 | GET | `/api/v1/agents/identity/status` | Analysis status | `identity_agent_api.rs:19` | -| 53 | POST | `/api/v1/agents/identity/suggest` | Name suggestions | `identity_agent_api.rs:20` | -| 54 | POST | `/api/v1/agents/suggest/merge` | Suggest identity merge | `identity_agent_api.rs` | -| 55 | POST | `/api/v1/agents/suggest/clustering` | Suggest re-clustering | `identity_agent_api.rs` | +| # | Method | Path | Description | +|---|--------|------|-------------| +| 51 | POST | `/api/v1/agents/identity/analyze` | Identify faces in file | +| 52 | GET | `/api/v1/agents/identity/status` | Analysis status | +| 53 | POST | `/api/v1/agents/identity/suggest` | Name suggestions | +| 54 | POST | `/api/v1/agents/suggest/merge` | Suggest merge | +| 55 | POST | `/api/v1/agents/suggest/clustering` | Suggest re-clustering | --- -## Summary - -| Category | Routes | Source | -|----------|--------|--------| -| System | 8 | `server.rs` | -| File Management | 10 | `server.rs`, `identity_api.rs` | -| Search | 8 | `server.rs`, `search.rs`, `universal_search.rs` | -| Face Trace | 2 | `trace_agent_api.rs` | -| Media | 4 | `media_api.rs` | -| Identities | 8 | `identity_api.rs`, `identities.rs` | -| Binding | 3 | `identity_binding.rs` | -| Resources | 3 | `identity_api.rs` | -| Agents (5W1H) | 4 | `five_w1h_agent_api.rs`, `agent_api.rs` | -| Agents (Identity) | 5 | `identity_agent_api.rs` | -| **Total** | **55** | | - ## Related - `API_DICTIONARY_V1.0.0.md` — Quick reference (56 endpoints)