From 85b06b6169d1e298914fa3ac7d4ecb8035f7380e Mon Sep 17 00:00:00 2001 From: Accusys Date: Fri, 15 May 2026 05:10:27 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20API=20ref=20=E2=80=94=20fix=20uuid?= =?UTF-8?q?=E2=86=92file=5Fuuid,=20add=20fps/end=5Fframe/end=5Ftime,=20dua?= =?UTF-8?q?l=20input,=20lookup,=20content=5Fhash,=20audio=20params?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs_v1.0/API_V1.0.0/API_REFERENCE_V1.0.0.md | 108 ++++++++++--------- 1 file changed, 60 insertions(+), 48 deletions(-) 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 40c4fe7..2a1bbb6 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 @@ -1,4 +1,4 @@ ---- + --- document_type: "reference_doc" service: "MOMENTRY_CORE" title: "Momentry Core Release API Reference v1.0.0" @@ -55,9 +55,17 @@ curl http://localhost:3002/health | 2a | GET | `/health/detailed` | Per-service health + resources + pipeline | ```bash -curl http://localhost:3002/health/detailed +curl -X POST http://localhost:3002/api/v1/files/register \ + -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \ + -H "Content-Type: application/json" \ + -d '{"file_path":"/path/to/video.mp4","content_hash":"optional-sha256-of-file"}' ``` ```json +{"success":true,"file_uuid":"3abeee81d94597629ed8cb943f182e94","duration":5954.0} +``` + +Supports all file types (video, image, document, audio). SHA256 content_hash computed automatically if not provided. +```json { "status": "ok", "build_git_hash": "26f2434", @@ -95,16 +103,17 @@ curl http://localhost:3002/health/detailed | # | Method | Path | Description | |---|--------|------|-------------| -| 9 | POST | `/api/v1/files/register` | Register video → file_uuid | -| 10 | POST | `/api/v1/unregister` | Unregister file(s): by `file_uuid` or pattern match (`file_path`+`pattern`) | -| 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/chunk/:chunk_id` | Single chunk detail (V1.0.2+) | -| 17 | GET | `/api/v1/progress/:file_uuid` | Processing progress | -| 18 | GET | `/api/v1/jobs` | Monitor jobs (filterable) | +| 9 | POST | `/api/v1/files/register` | Register file → file_uuid. Body: `{"file_path":"...", "content_hash":"optional"}` | +| 10 | GET | `/api/v1/files/lookup?file_name=` | Pre-upload name conflict check. Returns matches + `next_name` for auto-rename | +| 11 | POST | `/api/v1/unregister` | Unregister file(s): by `file_uuid` or pattern match (`file_path`+`pattern`) | +| 12 | GET | `/api/v1/files/scan` | Scan directory for new files | +| 13 | GET | `/api/v1/files` | List files (paginated) | +| 14 | GET | `/api/v1/file/:file_uuid` | Single file detail | +| 15 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata | +| 16 | POST | `/api/v1/file/:file_uuid/process` | Start pipeline | +| 17 | GET | `/api/v1/file/:file_uuid/chunk/:chunk_id` | Single chunk detail (V1.0.2+) | +| 18 | GET | `/api/v1/progress/:file_uuid` | Processing progress | +| 19 | GET | `/api/v1/jobs` | Monitor jobs (filterable) | ```bash curl -X POST http://localhost:3002/api/v1/files/register -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" -H "Content-Type: application/json" -d '{"file_path":"/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"}' @@ -145,24 +154,24 @@ curl "http://localhost:3002/api/v1/files?page=1&page_size=2" -H "X-API-Key: muse | # | 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 | +| 20 | POST | `/api/v1/search/visual` | Visual chunk search | +| 21 | POST | `/api/v1/search/visual/class` | By object class | +| 22 | POST | `/api/v1/search/visual/density` | By spatial density | +| 23 | POST | `/api/v1/search/visual/combination` | Combined visual search | +| 24 | POST | `/api/v1/search/visual/stats` | Visual stats | +| 25 | POST | `/api/v1/search/smart` | Semantic (EmbeddingGemma + pgvector) | +| 26 | POST | `/api/v1/search/universal` | BM25 keyword (requires file_uuid) | +| 27 | POST | `/api/v1/search/frames` | Frame-level search | ```bash -curl -X POST http://localhost:3002/api/v1/search/universal -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" -H "Content-Type: application/json" -d '{"query":"name","limit":2,"mode":"bm25","uuid":"3abeee81d94597629ed8cb943f182e94"}' +curl -X POST http://localhost:3002/api/v1/search/universal -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" -H "Content-Type: application/json" -d '{"query":"name","limit":2,"mode":"bm25","file_uuid":"3abeee81d94597629ed8cb943f182e94"}' ``` ```json {"query":"name","results":[{"chunk_id":"100","text":"What's your name?","start_time":258.68,"score":0.90}],"total":5,"page":1,"page_size":20,"took_ms":42} ``` ```bash -curl -X POST http://localhost:3002/api/v1/search/universal -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" -H "Content-Type: application/json" -d '{"query":"friends","limit":2,"mode":"bm25","uuid":"3abeee81d94597629ed8cb943f182e94"}' +curl -X POST http://localhost:3002/api/v1/search/universal -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" -H "Content-Type: application/json" -d '{"query":"friends","limit":2,"mode":"bm25","file_uuid":"3abeee81d94597629ed8cb943f182e94"}' ``` ```json {"query":"friends","results":[{"chunk_id":"104","text":"You won't find it difficult to make some new friends.","start_time":272.38,"score":0.90}],"total":3,"page":1,"page_size":20,"took_ms":38} @@ -174,8 +183,8 @@ curl -X POST http://localhost:3002/api/v1/search/universal -H "X-API-Key: muser | # | 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) | +| 28 | POST | `/api/v1/file/:file_uuid/face_trace/sortby` | List traces (sorted/filtered) | +| 29 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/faces` | Trace detections (+ interpolation) | ### sortby — list traces @@ -204,8 +213,8 @@ Parameters: curl "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/trace/2/faces?limit=2&interpolate=true" -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" ``` ```json -{"success":true,"trace_id":2,"total":1,"faces":[ - {"id":12399,"start_frame":4620,"start_time":184.8,"x":787,"y":582,"width":225,"height":225,"confidence":0.666,"interpolated":false} +{"success":true,"trace_id":2,"fps":25.0,"total":1,"faces":[ + {"id":12399,"start_frame":4620,"end_frame":4620,"start_time":184.8,"end_time":184.8,"x":787,"y":582,"width":225,"height":225,"confidence":0.666,"interpolated":false} ]} ``` @@ -215,14 +224,17 @@ curl "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/trace/2 | # | 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_time=&end_time=` seconds) | -| 31 | GET | `/api/v1/file/:file_uuid/video/bbox` | Bbox overlay (`?start_frame=&end_frame=&face_uuid=&duration=` frames) | -| 32 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | Trace clip (?mode=&padding=) | +| 30 | GET | `/api/v1/file/:file_uuid/thumbnail` | Frame JPEG (?frame=&x=&y=&w=&h=) | +| 31 | GET | `/api/v1/file/:file_uuid/video` | Raw video stream. Dual input: `?start_time=&end_time=` (seconds) or `?start_frame=&end_frame=` (frames). | +| 32 | GET | `/api/v1/file/:file_uuid/video/bbox` | Bbox overlay. `?start_frame=&end_frame=&face_uuid=&duration=` (all frame numbers). Dual input via `start_time`/`end_time`. | +| 33 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | Trace clip (?mode=&padding=&audio=) | -Two modes: -- `mode=normal` (default): raw clip, `-c copy`, no overlay -- `mode=debug`: text overlay + green bounding boxes +All video endpoints support: +- `mode=normal|debug` (default: `normal`) +- `audio=on|off` (default: `on`) + +`mode=normal`: raw clip, `-c copy`, no overlay. +`mode=debug`: re-encoded with top-left text info + green bboxes (trace labels at actual frames with thickness=4, interpolated at first known position with thickness=1). ```bash # Normal mode @@ -283,9 +295,9 @@ curl "http://localhost:3002/api/v1/faces/candidates?page=1&page_size=2" -H "X-A | # | 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/:identity_uuid/mergeinto` | Merge into another identity | +| 43 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity | +| 44 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity | +| 45 | 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"}' @@ -300,9 +312,9 @@ curl -X POST "http://localhost:3002/api/v1/identity/a9a90105-6d6b-46ff-92da-0c3c | # | 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 | +| 46 | POST | `/api/v1/resource/register` | Register processing resource | +| 47 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat | +| 48 | GET | `/api/v1/resources` | List all resources | ```bash curl "http://localhost:3002/api/v1/resources" -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" @@ -317,10 +329,10 @@ curl "http://localhost:3002/api/v1/resources" -H "X-API-Key: muser_686008560363 | # | 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 | +| 49 | POST | `/api/v1/agents/translate` | AI text translation | +| 50 | POST | `/api/v1/agents/5w1h/analyze` | Single chunk analysis | +| 51 | POST | `/api/v1/agents/5w1h/batch` | Batch analysis | +| 52 | GET | `/api/v1/agents/5w1h/status` | Job status | ```bash curl -X POST "http://localhost:3002/api/v1/agents/translate" -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" -H "Content-Type: application/json" -d '{"text":"Hello world","target_language":"zh-TW"}' @@ -335,11 +347,11 @@ curl -X POST "http://localhost:3002/api/v1/agents/translate" -H "X-API-Key: mus | # | 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 | +| 53 | POST | `/api/v1/agents/identity/analyze` | Identify faces in file | +| 54 | GET | `/api/v1/agents/identity/status` | Analysis status | +| 55 | POST | `/api/v1/agents/identity/suggest` | Name suggestions | +| 56 | POST | `/api/v1/agents/suggest/merge` | Suggest merge | +| 57 | POST | `/api/v1/agents/suggest/clustering` | Suggest re-clustering | ---