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

docs: clarify file_uuid vs identity_uuid across all API docs

Browse Source
This commit is contained in:
Accusys
2026-05-14 17:19:57 +08:00
parent 0da90630f5
commit 89c3b7df50
5 changed files with 16 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -41,7 +41,7 @@ Every path segment after the resource ID is a **verb** — an action on that res
- 單一實體下唯一 ID → `id`（`trace_id`, `chunk_id`, `face_id`） - 單一實體下唯一 ID → `id`（`trace_id`, `chunk_id`, `face_id`）
- 路徑尾端 → 動詞（`/video`, `/chunks`, `/bind`） - 路徑尾端 → 動詞（`/video`, `/chunks`, `/bind`）
- 集合列表 → **複數**（`/files`, `/identities`, `/resources`, `/faces`） - 集合列表 → **複數**（`/files`, `/identities`, `/resources`, `/faces`）
- 單一資源操作 → **單數**（`/file/:uuid`, `/identity/:uuid`） - 單一資源操作 → **單數**（`/file/:file_uuid`, `/identity/:identity_uuid`）
## Legend ## Legend
@@ -60,7 +60,7 @@ Every path segment after the resource ID is a **verb** — an action on that res
| 5 | GET | `/api/v1/stats/ingest` | Ingest statistics | | 5 | GET | `/api/v1/stats/ingest` | Ingest statistics |
| 6 | GET | `/api/v1/stats/sftpgo` | SFTPGo service status | | 6 | GET | `/api/v1/stats/sftpgo` | SFTPGo service status |
| 7 | GET | `/api/v1/stats/inference` | LLM/embedding health | | 7 | GET | `/api/v1/stats/inference` | LLM/embedding health |
| 8 | POST | `/api/v1/files/register` | Register video file → UUID | | 8 | POST | `/api/v1/files/register` | Register video file → file_uuid |
| 9 | POST | `/api/v1/unregister` | Delete file + all data | | 9 | POST | `/api/v1/unregister` | Delete file + all data |
| 10 | GET | `/api/v1/files/scan` | Scan directory for new files | | 10 | GET | `/api/v1/files/scan` | Scan directory for new files |
| 11 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata | | 11 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata |
@@ -98,7 +98,7 @@ Every path segment after the resource ID is a **verb** — an action on that res
|---|--------|-------|-------------| |---|--------|-------|-------------|
| 34 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity | | 34 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity |
| 35 | POST | `/api/v1/identity/: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_uuid/mergeinto` | Merge identities | | 36 | POST | `/api/v1/identity/:identity_uuid/mergeinto` | Merge identity :identity_uuid → target |
## Face Candidates (identities.rs) ## Face Candidates (identities.rs)
@@ -111,7 +111,7 @@ Every path segment after the resource ID is a **verb** — an action on that res
| # | Method | Route | Description | | # | Method | Route | Description |
|---|--------|-------|-------------| |---|--------|-------|-------------|
| 38 | POST | `/api/v1/search/smart` | Semantic search (EmbeddingGemma + pgvector) | | 38 | POST | `/api/v1/search/smart` | Semantic search (EmbeddingGemma + pgvector) |
| 39 | POST | `/api/v1/search/universal` | BM25 keyword search (requires uuid) | | 39 | POST | `/api/v1/search/universal` | BM25 keyword search (requires file_uuid) |
| 40 | POST | `/api/v1/search/frames` | Frame-level search | | 40 | POST | `/api/v1/search/frames` | Frame-level search |
## Trace (trace_agent_api.rs) ## Trace (trace_agent_api.rs)
@@ -155,7 +155,7 @@ Every path segment after the resource ID is a **verb** — an action on that res
| # | Method | Route | Description | | # | Method | Route | Description |
|---|--------|-------|-------------| |---|--------|-------|-------------|
| 57 | GET | `/api/v1/identities/search?q=` | Search identities by name → chunk results | | 57 | GET | `/api/v1/identities/search?q=` | Search identities by name → chunk results |
| 58 | GET | `/api/v1/search/identity_text?q=&uuid=` | Full-text search → identity-bound chunks | | 58 | GET | `/api/v1/search/identity_text?q=&file_uuid=` | Full-text search → identity-bound chunks |
--- ---

2
docs_v1.0/API_V1.0.0/API_DOCUMENTATION_V1.0.0.md
View File

@@ -269,7 +269,7 @@ Response `200`:
``` ```
GET /api/v1/files GET /api/v1/files
Query: ?page=1&page_size=10&uuid=xxx Query: ?page=1&page_size=10&file_uuid=xxx
``` ```
Response `200`: Response `200`:

8
docs_v1.0/API_V1.0.0/API_REFERENCE_V1.0.0.md
View File

@@ -217,9 +217,9 @@ Two modes:
```bash ```bash
# Normal mode # Normal mode
curl -o trace.mp4 "http://localhost:3002/api/v1/file/{uuid}/trace/42/video?mode=normal" curl -o trace.mp4 "http://localhost:3002/api/v1/file/{file_uuid}/trace/42/video?mode=normal"
# Debug mode # Debug mode
curl -o trace_debug.mp4 "http://localhost:3002/api/v1/file/{uuid}/trace/42/video?mode=debug" curl -o trace_debug.mp4 "http://localhost:3002/api/v1/file/{file_uuid}/trace/42/video?mode=debug"
``` ```
Debug overlay shows at bottom-left: Debug overlay shows at bottom-left:
@@ -248,7 +248,7 @@ Green bbox per face detection: actual frames `thickness=4`, interpolated `thickn
| 39 | GET | `/api/v1/identity/:identity_uuid/chunks` | Chunks for identity | | 39 | GET | `/api/v1/identity/:identity_uuid/chunks` | Chunks for identity |
| 40 | GET | `/api/v1/faces/candidates` | Unbound face gallery | | 40 | GET | `/api/v1/faces/candidates` | Unbound face gallery |
| 41 | GET | `/api/v1/identities/search?q=` | Search identities by name → chunks | | 41 | GET | `/api/v1/identities/search?q=` | Search identities by name → chunks |
| 42 | GET | `/api/v1/search/identity_text?q=&uuid=` | Full-text search → identity chunks | | 42 | GET | `/api/v1/search/identity_text?q=&file_uuid=` | Full-text search → identity-bound chunks |
```bash ```bash
curl "http://localhost:3002/api/v1/identities?page=1&page_size=3" -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" curl "http://localhost:3002/api/v1/identities?page=1&page_size=3" -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
@@ -276,7 +276,7 @@ curl "http://localhost:3002/api/v1/faces/candidates?page=1&page_size=2" -H "X-A
|---|--------|------|-------------| |---|--------|------|-------------|
| 41 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity | | 41 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity |
| 42 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity | | 42 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity |
| 43 | POST | `/api/v1/identity/:from_uuid/mergeinto` | Merge two identities | | 43 | POST | `/api/v1/identity/:identity_uuid/mergeinto` | Merge into another identity |
```bash ```bash
curl -X POST "http://localhost:3002/api/v1/identity/a9a90105-6d6b-46ff-92da-0c3c1a57dff4/bind" -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" -H "Content-Type: application/json" -d '{"file_uuid":"3abeee81d94597629ed8cb943f182e94","face_id":"face_42"}' curl -X POST "http://localhost:3002/api/v1/identity/a9a90105-6d6b-46ff-92da-0c3c1a57dff4/bind" -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" -H "Content-Type: application/json" -d '{"file_uuid":"3abeee81d94597629ed8cb943f182e94","face_id":"face_42"}'

15
docs_v1.0/API_V1.0.0/API_USAGE_GUIDE_V1.0.0.md
View File

@@ -27,16 +27,9 @@ sequenceDiagram
flowchart LR flowchart LR
A[上傳影片] --> B[POST /files/register] A[上傳影片] --> B[POST /files/register]
B --> C[取得 file_uuid] B --> C[取得 file_uuid]
C --> D[POST /file/:uuid/process] C --> D[POST /file/:file_uuid/process]
D --> E{7 Processors} ...
E --> F[ASR] F --> M[GET /progress/:file_uuid]
E --> G[ASRX]
E --> H[CUT]
E --> I[FACE]
E --> J[OCR]
E --> K[POSE]
E --> L[YOLO]
F --> M[GET /progress/:uuid]
G --> M G --> M
H --> M H --> M
I --> M I --> M
@@ -169,7 +162,7 @@ mindmap
Identities Identities
GET /identities GET /identities
POST /identity POST /identity
POST /identity/:uuid/bind POST /identity/:identity_uuid/bind
Agents Agents
POST /agents/translate POST /agents/translate
POST /agents/5w1h/analyze POST /agents/5w1h/analyze

4
docs_v1.0/API_V1.0.0/TRACE/TRACE_API_REFERENCE_V1.0.0.md
View File

@@ -204,10 +204,10 @@ Green bbox: actual detection frames `thickness=4`, interpolated `thickness=1`.
**Usage:** **Usage:**
```bash ```bash
# Normal mode (default) # Normal mode (default)
curl -o trace.mp4 "https://host/api/v1/file/{uuid}/trace/{id}/video?mode=normal" curl -o trace.mp4 "https://host/api/v1/file/{file_uuid}/trace/{trace_id}/video?mode=normal"
# Debug mode # Debug mode
curl -o trace.mp4 "https://host/api/v1/file/{uuid}/trace/{id}/video?mode=debug" curl -o trace.mp4 "https://host/api/v1/file/{file_uuid}/trace/{trace_id}/video?mode=debug"
``` ```
--- ---