From 89c3b7df50cae02c122b8201522849c64e3f2877 Mon Sep 17 00:00:00 2001 From: Accusys Date: Thu, 14 May 2026 17:19:57 +0800 Subject: [PATCH] docs: clarify file_uuid vs identity_uuid across all API docs --- docs_v1.0/API_V1.0.0/API_DICTIONARY_V1.0.0.md | 10 +++++----- docs_v1.0/API_V1.0.0/API_DOCUMENTATION_V1.0.0.md | 2 +- docs_v1.0/API_V1.0.0/API_REFERENCE_V1.0.0.md | 8 ++++---- docs_v1.0/API_V1.0.0/API_USAGE_GUIDE_V1.0.0.md | 15 ++++----------- .../TRACE/TRACE_API_REFERENCE_V1.0.0.md | 4 ++-- 5 files changed, 16 insertions(+), 23 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 4841b7c..fd0bdd9 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 @@ -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`） - 路徑尾端 → 動詞（`/video`, `/chunks`, `/bind`） - 集合列表 → **複數**（`/files`, `/identities`, `/resources`, `/faces`） -- 單一資源操作 → **單數**（`/file/:uuid`, `/identity/:uuid`） +- 單一資源操作 → **單數**（`/file/:file_uuid`, `/identity/:identity_uuid`） ## 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 | | 6 | GET | `/api/v1/stats/sftpgo` | SFTPGo service status | | 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 | | 10 | GET | `/api/v1/files/scan` | Scan directory for new files | | 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 | | 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) @@ -111,7 +111,7 @@ Every path segment after the resource ID is a **verb** — an action on that res | # | Method | Route | Description | |---|--------|-------|-------------| | 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 | ## 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 | |---|--------|-------|-------------| | 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 | --- diff --git a/docs_v1.0/API_V1.0.0/API_DOCUMENTATION_V1.0.0.md b/docs_v1.0/API_V1.0.0/API_DOCUMENTATION_V1.0.0.md index bf35699..82cbf11 100644 --- a/docs_v1.0/API_V1.0.0/API_DOCUMENTATION_V1.0.0.md +++ b/docs_v1.0/API_V1.0.0/API_DOCUMENTATION_V1.0.0.md @@ -269,7 +269,7 @@ Response `200`: ``` GET /api/v1/files -Query: ?page=1&page_size=10&uuid=xxx +Query: ?page=1&page_size=10&file_uuid=xxx ``` Response `200`: diff --git a/docs_v1.0/API_V1.0.0/API_REFERENCE_V1.0.0.md b/docs_v1.0/API_V1.0.0/API_REFERENCE_V1.0.0.md index 8d9e9ed..12d4f8b 100644 --- a/docs_v1.0/API_V1.0.0/API_REFERENCE_V1.0.0.md +++ b/docs_v1.0/API_V1.0.0/API_REFERENCE_V1.0.0.md @@ -217,9 +217,9 @@ Two modes: ```bash # 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 -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: @@ -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 | | 40 | GET | `/api/v1/faces/candidates` | Unbound face gallery | | 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 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 | | 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 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"}' diff --git a/docs_v1.0/API_V1.0.0/API_USAGE_GUIDE_V1.0.0.md b/docs_v1.0/API_V1.0.0/API_USAGE_GUIDE_V1.0.0.md index 3dd1b7c..ae3e8bd 100644 --- a/docs_v1.0/API_V1.0.0/API_USAGE_GUIDE_V1.0.0.md +++ b/docs_v1.0/API_V1.0.0/API_USAGE_GUIDE_V1.0.0.md @@ -27,16 +27,9 @@ sequenceDiagram flowchart LR A[上傳影片] --> B[POST /files/register] B --> C[取得 file_uuid] - C --> D[POST /file/:uuid/process] - D --> E{7 Processors} - E --> F[ASR] - E --> G[ASRX] - E --> H[CUT] - E --> I[FACE] - E --> J[OCR] - E --> K[POSE] - E --> L[YOLO] - F --> M[GET /progress/:uuid] + C --> D[POST /file/:file_uuid/process] + ... + F --> M[GET /progress/:file_uuid] G --> M H --> M I --> M @@ -169,7 +162,7 @@ mindmap Identities GET /identities POST /identity - POST /identity/:uuid/bind + POST /identity/:identity_uuid/bind Agents POST /agents/translate POST /agents/5w1h/analyze diff --git a/docs_v1.0/API_V1.0.0/TRACE/TRACE_API_REFERENCE_V1.0.0.md b/docs_v1.0/API_V1.0.0/TRACE/TRACE_API_REFERENCE_V1.0.0.md index 9e703c1..740608f 100644 --- a/docs_v1.0/API_V1.0.0/TRACE/TRACE_API_REFERENCE_V1.0.0.md +++ b/docs_v1.0/API_V1.0.0/TRACE/TRACE_API_REFERENCE_V1.0.0.md @@ -204,10 +204,10 @@ Green bbox: actual detection frames `thickness=4`, interpolated `thickness=1`. **Usage:** ```bash # 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 -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" ``` ---