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

docs: API ref — fix uuid→file_uuid, add fps/end_frame/end_time, dual input, lookup, content_hash, audio params

Browse Source
This commit is contained in:
Accusys
2026-05-15 05:10:27 +08:00
parent a66bd6b7c2
commit 85b06b6169
1 changed files with 60 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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 |
---