admin/momentry_core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: remove .rs annotations, fix :uuid→:file_uuid, :id→:trace_id

Browse Source
This commit is contained in:
Warren
2026-05-08 04:25:15 +08:00
parent cad5eadeec
commit 7a193845bb
2 changed files with 105 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs_v1.0/API_V1.0.0/API_DICTIONARY_V1.0.0.md
View File

@@ -27,7 +27,7 @@
| 11 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata | | 11 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata |
| 12 | POST | `/api/v1/file/:file_uuid/process` | Start processing pipeline | | 12 | POST | `/api/v1/file/:file_uuid/process` | Start processing pipeline |
| 13 | GET | `/api/v1/file/:file_uuid/chunks` | List pre-chunks for file | | 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) | | 15 | GET | `/api/v1/jobs` | List monitor jobs (filterable by status) |
| 16 | POST | `/api/v1/config/cache` | Toggle Redis cache | | 16 | POST | `/api/v1/config/cache` | Toggle Redis cache |
| 17 | POST | `/api/v1/search/visual` | Search visual chunks | | 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 | | 24 | GET | `/api/v1/file/:file_uuid/identities` | Identities in this file |
| 25 | GET | `/api/v1/identities` | List all identities | | 25 | GET | `/api/v1/identities` | List all identities |
| 26 | POST | `/api/v1/identity` | Register new identity | | 26 | POST | `/api/v1/identity` | Register new identity |
| 27 | GET | `/api/v1/identity/:uuid` | Identity detail | | 27 | GET | `/api/v1/identity/:identity_uuid` | Identity detail |
| 28 | DELETE | `/api/v1/identity/:uuid` | Delete identity | | 28 | DELETE | `/api/v1/identity/:identity_uuid` | Delete identity |
| 29 | GET | `/api/v1/identity/:uuid/files` | Files for an identity | | 29 | GET | `/api/v1/identity/:identity_uuid/files` | Files for an identity |
| 30 | GET | `/api/v1/identity/:uuid/chunks` | Chunks for an identity | | 30 | GET | `/api/v1/identity/:identity_uuid/chunks` | Chunks for an identity |
| 31 | POST | `/api/v1/resource/register` | Register processing resource | | 31 | POST | `/api/v1/resource/register` | Register processing resource |
| 32 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat | | 32 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat |
| 33 | GET | `/api/v1/resources` | List all resources | | 33 | GET | `/api/v1/resources` | List all resources |
@@ -57,9 +57,9 @@
| # | Method | Route | Description | | # | Method | Route | Description |
|---|--------|-------|-------------| |---|--------|-------|-------------|
| 34 | POST | `/api/v1/identity/:uuid/bind` | Bind face → identity | | 34 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity |
| 35 | POST | `/api/v1/identity/:uuid/unbind` | Unbind face from identity | | 35 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity |
| 36 | POST | `/api/v1/identity/:from/mergeinto` | Merge identities | | 36 | POST | `/api/v1/identity/:from_uuid/mergeinto` | Merge identities |
## Face Candidates (identities.rs) ## Face Candidates (identities.rs)
@@ -79,23 +79,23 @@
| # | Method | Route | Description | | # | Method | Route | Description |
|---|--------|-------|-------------| |---|--------|-------|-------------|
| 41 | POST | `/api/v1/file/:uuid/face_trace/sortby` | List traces (sorted/filtered) | | 41 | POST | `/api/v1/file/:file_uuid/face_trace/sortby` | List traces (sorted/filtered) |
| 42 | GET | `/api/v1/file/:uuid/trace/:id/faces` | Single trace detections + interpolation | | 42 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/faces` | Single trace detections + interpolation |
## Media (media_api.rs) ## Media (media_api.rs)
| # | Method | Route | Description | | # | Method | Route | Description |
|---|--------|-------|-------------| |---|--------|-------|-------------|
| 43 | GET | `/api/v1/file/:uuid/thumbnail` | Frame JPEG (optional crop via `?frame=&x=&y=&w=&h=`) | | 43 | GET | `/api/v1/file/: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) | | 44 | GET | `/api/v1/file/:file_uuid/video` | Raw video stream (`?start=&end=` for range) |
| 45 | GET | `/api/v1/file/:uuid/video/bbox` | Bbox overlay video (`?start=&end=&duration=`) | | 45 | GET | `/api/v1/file/: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=`) | | 46 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | Trace clip with bbox overlay (`?padding=`) |
## Identity Delete ## Identity Delete
| # | Method | Route | Description | | # | 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) ## Agents (agent_api.rs + five_w1h_agent_api.rs + identity_agent_api.rs)

215
docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_v1.0.0.md
View File

@@ -20,83 +20,73 @@ owner: "Warren"
| Development | `http://localhost:3003` | | Development | `http://localhost:3003` |
| Auth | Header `X-API-Key: <key>` (login endpoint unprotected) | | Auth | Header `X-API-Key: <key>` (login endpoint unprotected) |
## 1. System (server.rs) ## 1. System
| # | Method | Path | Description | File:Line | | # | Method | Path | Description |
|---|--------|------|-------------|-----------| |---|--------|------|-------------|
| 1 | GET | `/health` | Server status (ok/degraded) | `server.rs:2529` | | 1 | GET | `/health` | Server status (ok/degraded) |
| 2 | GET | `/health/detailed` | Per-service health + latency | `server.rs:2530` | | 2 | GET | `/health/detailed` | Per-service health + latency |
| 3 | POST | `/api/v1/auth/login` | Username/password → API key | `server.rs:2531` | | 3 | POST | `/api/v1/auth/login` | Username/password → API key |
| 4 | POST | `/api/v1/auth/logout` | Invalidate session | `server.rs:2532` | | 4 | POST | `/api/v1/auth/logout` | Invalidate session |
| 5 | GET | `/api/v1/stats/ingest` | Ingest statistics | `server.rs:2533` | | 5 | GET | `/api/v1/stats/ingest` | Ingest statistics |
| 6 | GET | `/api/v1/stats/sftpgo` | SFTPGo status | `server.rs:2534` | | 6 | GET | `/api/v1/stats/sftpgo` | SFTPGo status |
| 7 | GET | `/api/v1/stats/inference` | LLM/Embedding health | `server.rs:2535` | | 7 | GET | `/api/v1/stats/inference` | LLM/Embedding health |
| 8 | POST | `/api/v1/config/cache` | Toggle Redis cache | `server.rs:2513` | | 8 | POST | `/api/v1/config/cache` | Toggle Redis cache |
**Example:** **Example:**
```bash ```bash
GET /health GET /health
→ {"status":"ok","version":"1.0.0","uptime_ms":248233} → {"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 | | # | Method | Path | Description |
|---|--------|------|-------------|-----------| |---|--------|------|-------------|
| 9 | POST | `/api/v1/files/register` | Register video → UUID | `server.rs:2505` | | 9 | POST | `/api/v1/files/register` | Register video → file_uuid |
| 10 | POST | `/api/v1/unregister` | Delete file + all data | `server.rs:2506` | | 10 | POST | `/api/v1/unregister` | Delete file + all data |
| 11 | GET | `/api/v1/files/scan` | Scan directory for new files | `server.rs:2507` | | 11 | GET | `/api/v1/files/scan` | Scan directory for new files |
| 12 | GET | `/api/v1/file/:file_uuid` | Single file detail | `identity_api.rs:16` | | 12 | GET | `/api/v1/files` | List files (paginated) |
| 13 | GET | `/api/v1/files` | List files (paginated) | `identity_api.rs:15` | | 13 | GET | `/api/v1/file/:file_uuid` | Single file detail |
| 14 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata | `server.rs:2508` | | 14 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata |
| 15 | POST | `/api/v1/file/:file_uuid/process` | Start pipeline | `server.rs:2509` | | 15 | POST | `/api/v1/file/:file_uuid/process` | Start pipeline |
| 16 | GET | `/api/v1/file/:file_uuid/chunks` | List pre-chunks | `server.rs:2510` | | 16 | GET | `/api/v1/file/:file_uuid/chunks` | List pre-chunks |
| 17 | GET | `/api/v1/progress/:uuid` | Processing progress | `server.rs:2511` | | 17 | GET | `/api/v1/progress/:file_uuid` | Processing progress |
| 18 | GET | `/api/v1/jobs` | Monitor jobs (filterable) | `server.rs:2512` | | 18 | GET | `/api/v1/jobs` | Monitor jobs (filterable) |
**Example:** **Example:**
```bash ```bash
POST /api/v1/files/register POST /api/v1/files/register
{"file_path":"/sftpgo/data/demo/video.mp4"} {"file_path":"/sftpgo/data/demo/video.mp4"}
→ {"success":true,"file_uuid":"3abeee81...","duration":5954.0,...} → {"success":true,"file_uuid":"3abeee81...","duration":5954.0}
GET /api/v1/files?page=1&page_size=5
→ {"files":[...],"total":37,"page":1}
``` ```
## 3. Search (server.rs + search.rs + universal_search.rs) ## 3. Search
| # | Method | Path | Description | File:Line | | # | Method | Path | Description |
|---|--------|------|-------------|-----------| |---|--------|------|-------------|
| 19 | POST | `/api/v1/search/visual` | Visual chunk search | `server.rs:2536` | | 19 | POST | `/api/v1/search/visual` | Visual chunk search |
| 20 | POST | `/api/v1/search/visual/class` | By object class | `server.rs:2541` | | 20 | POST | `/api/v1/search/visual/class` | By object class |
| 21 | POST | `/api/v1/search/visual/density` | By spatial density | `server.rs:2546` | | 21 | POST | `/api/v1/search/visual/density` | By spatial density |
| 22 | POST | `/api/v1/search/visual/combination` | Combined visual search | `server.rs:2541` | | 22 | POST | `/api/v1/search/visual/combination` | Combined visual search |
| 23 | POST | `/api/v1/search/visual/stats` | Visual stats | `server.rs:2545` | | 23 | POST | `/api/v1/search/visual/stats` | Visual stats |
| 24 | POST | `/api/v1/search/smart` | Semantic (EmbeddingGemma + pgvector) | `search.rs:164` | | 24 | POST | `/api/v1/search/smart` | Semantic (EmbeddingGemma + pgvector) |
| 25 | POST | `/api/v1/search/universal` | BM25 keyword (requires uuid) | `universal_search.rs:94` | | 25 | POST | `/api/v1/search/universal` | BM25 keyword (requires file_uuid) |
| 26 | POST | `/api/v1/search/frames` | Frame-level search | `universal_search.rs:95` | | 26 | POST | `/api/v1/search/frames` | Frame-level search |
**Example:** **Example:**
```bash ```bash
POST /api/v1/search/universal POST /api/v1/search/universal
{"query":"friends","mode":"bm25","uuid":"3abeee81..."} {"query":"friends","mode":"bm25","file_uuid":"3abeee81..."}
→ {"count":1,"results":[{"text":"You won't find it difficult to make some new friends.",...}]} → {"count":1,"results":[{"text":"You won't find it difficult..."}]}
POST /api/v1/search/smart
{"query":"Audrey Hepburn","uuid":"3abeee81..."}
→ {"strategy":"semantic_vector_search","results":[...]}
``` ```
## 4. Face Trace (trace_agent_api.rs) ## 4. Face Trace
| # | Method | Path | Description | File:Line | | # | Method | Path | Description |
|---|--------|------|-------------|-----------| |---|--------|------|-------------|
| 27 | POST | `/api/v1/file/:uuid/face_trace/sortby` | List traces (sorted/filtered) | `trace_agent_api.rs:14` | | 27 | POST | `/api/v1/file/:file_uuid/face_trace/sortby` | List traces (sorted/filtered) |
| 28 | GET | `/api/v1/file/:uuid/trace/:id/faces` | Trace detections (+ interpolation) | `trace_agent_api.rs:18` | | 28 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/faces` | Trace detections (+ interpolation) |
**Parameters:** **Parameters:**
- `sort_by`: `face_count` | `duration` | `first_appearance` - `sort_by`: `face_count` | `duration` | `first_appearance`
@@ -108,53 +98,44 @@ POST /api/v1/search/smart
POST /api/v1/file/3abeee81.../face_trace/sortby POST /api/v1/file/3abeee81.../face_trace/sortby
{"sort_by":"face_count","limit":3} {"sort_by":"face_count","limit":3}
→ {"total_traces":6892,"total_faces":108204, → {"total_traces":6892,"total_faces":108204,
"traces":[{"trace_id":3128,"face_count":1109,...}]} "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,...}]}
``` ```
## 5. Media (media_api.rs) ## 5. Media
| # | Method | Path | Description | File:Line | | # | Method | Path | Description |
|---|--------|------|-------------|-----------| |---|--------|------|-------------|
| 29 | GET | `/api/v1/file/:uuid/thumbnail` | Frame JPEG (optional crop) | `media_api.rs:23` | | 29 | GET | `/api/v1/file/:file_uuid/thumbnail` | Frame JPEG (?frame=&x=&y=&w=&h=) |
| 30 | GET | `/api/v1/file/:uuid/video` | Raw video stream | `media_api.rs:18` | | 30 | GET | `/api/v1/file/:file_uuid/video` | Raw video stream (?start=&end=) |
| 31 | GET | `/api/v1/file/:uuid/video/bbox` | Bbox overlay video | `media_api.rs:14` | | 31 | GET | `/api/v1/file/:file_uuid/video/bbox` | Bbox overlay (?start=&end=&duration=) |
| 32 | GET | `/api/v1/file/:uuid/trace/:id/video` | Trace clip with bbox | `media_api.rs:22` | | 32 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | Trace clip (?padding=) |
**Parameters:** ## 6. Identities
- `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 (identity_api.rs + identities.rs) | # | Method | Path | Description |
|---|--------|------|-------------|
| # | Method | Path | Description | File:Line | | 33 | GET | `/api/v1/identities` | List all identities |
|---|--------|------|-------------|-----------| | 34 | GET | `/api/v1/file/:file_uuid/identities` | Identities in a file |
| 33 | GET | `/api/v1/identities` | List all identities | `identity_api.rs:17` | | 35 | POST | `/api/v1/identity` | Register new identity |
| 34 | GET | `/api/v1/file/:uuid/identities` | Identities in a file | `identity_api.rs:21` | | 36 | GET | `/api/v1/identity/:identity_uuid` | Identity detail |
| 35 | POST | `/api/v1/identity` | Register new identity | `identities.rs:34` | | 37 | DELETE | `/api/v1/identity/:identity_uuid` | Delete identity |
| 36 | GET | `/api/v1/identity/:uuid` | Identity detail | `identity_api.rs:25` | | 38 | GET | `/api/v1/identity/:identity_uuid/files` | Files for identity |
| 37 | DELETE | `/api/v1/identity/:uuid` | Delete identity | `identity_api.rs:29` | | 39 | GET | `/api/v1/identity/:identity_uuid/chunks` | Chunks for identity |
| 38 | GET | `/api/v1/identity/:uuid/files` | Files for identity | `identity_api.rs:33` | | 40 | GET | `/api/v1/faces/candidates` | Unbound face gallery |
| 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` |
**Example:** **Example:**
```bash ```bash
GET /api/v1/identities?page=1&page_size=5 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 | | # | Method | Path | Description |
|---|--------|------|-------------|-----------| |---|--------|------|-------------|
| 41 | POST | `/api/v1/identity/:uuid/bind` | Bind face → identity | `identity_binding.rs:291` | | 41 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity |
| 42 | POST | `/api/v1/identity/:uuid/unbind` | Unbind face from identity | `identity_binding.rs:292` | | 42 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity |
| 43 | POST | `/api/v1/identity/:from/mergeinto` | Merge two identities | `identity_binding.rs:296` | | 43 | POST | `/api/v1/identity/:from_uuid/mergeinto` | Merge two identities |
**Example:** **Example:**
```bash ```bash
@@ -163,51 +144,35 @@ POST /api/v1/identity/a9a90105.../bind
→ {"success":true} → {"success":true}
``` ```
## 8. Resources (identity_api.rs) ## 8. Resources
| # | Method | Path | Description | File:Line | | # | Method | Path | Description |
|---|--------|------|-------------|-----------| |---|--------|------|-------------|
| 44 | POST | `/api/v1/resource/register` | Register processing resource | `identity_api.rs:35` | | 44 | POST | `/api/v1/resource/register` | Register processing resource |
| 45 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat | `identity_api.rs:34` | | 45 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat |
| 46 | GET | `/api/v1/resources` | List all resources | `identity_api.rs:33` | | 46 | GET | `/api/v1/resources` | List all resources |
## 9. Agents — 5W1H (five_w1h_agent_api.rs) ## 9. Agents — 5W1H
| # | Method | Path | Description | File:Line | | # | Method | Path | Description |
|---|--------|------|-------------|-----------| |---|--------|------|-------------|
| 47 | POST | `/api/v1/agents/translate` | AI text translation | `agent_api.rs:8` | | 47 | POST | `/api/v1/agents/translate` | AI text translation |
| 48 | POST | `/api/v1/agents/5w1h/analyze` | Single chunk analysis | `five_w1h_agent_api.rs:20` | | 48 | POST | `/api/v1/agents/5w1h/analyze` | Single chunk analysis |
| 49 | POST | `/api/v1/agents/5w1h/batch` | Batch analysis | `five_w1h_agent_api.rs:21` | | 49 | POST | `/api/v1/agents/5w1h/batch` | Batch analysis |
| 50 | GET | `/api/v1/agents/5w1h/status` | Job status | `five_w1h_agent_api.rs:22` | | 50 | GET | `/api/v1/agents/5w1h/status` | Job status |
## 10. Agents — Identity (identity_agent_api.rs) ## 10. Agents — Identity
| # | Method | Path | Description | File:Line | | # | Method | Path | Description |
|---|--------|------|-------------|-----------| |---|--------|------|-------------|
| 51 | POST | `/api/v1/agents/identity/analyze` | Identify faces in file | `identity_agent_api.rs:17` | | 51 | POST | `/api/v1/agents/identity/analyze` | Identify faces in file |
| 52 | GET | `/api/v1/agents/identity/status` | Analysis status | `identity_agent_api.rs:19` | | 52 | GET | `/api/v1/agents/identity/status` | Analysis status |
| 53 | POST | `/api/v1/agents/identity/suggest` | Name suggestions | `identity_agent_api.rs:20` | | 53 | POST | `/api/v1/agents/identity/suggest` | Name suggestions |
| 54 | POST | `/api/v1/agents/suggest/merge` | Suggest identity merge | `identity_agent_api.rs` | | 54 | POST | `/api/v1/agents/suggest/merge` | Suggest merge |
| 55 | POST | `/api/v1/agents/suggest/clustering` | Suggest re-clustering | `identity_agent_api.rs` | | 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 ## Related
- `API_DICTIONARY_V1.0.0.md` — Quick reference (56 endpoints) - `API_DICTIONARY_V1.0.0.md` — Quick reference (56 endpoints)