docs: add real curl examples with verified responses
This commit is contained in:
Warren
@@ -10,7 +10,7 @@ owner: "Warren"
|
||||
|
||||
# Momentry Core API Reference v1.0.0
|
||||
|
||||
56 endpoints across 10 categories.
|
||||
56 endpoints across 10 categories, with real curl examples and responses.
|
||||
|
||||
## Base
|
||||
|
||||
@@ -20,6 +20,8 @@ owner: "Warren"
|
||||
| Development | `http://localhost:3003` |
|
||||
| Auth | Header `X-API-Key: <key>` (login endpoint unprotected) |
|
||||
|
||||
---
|
||||
|
||||
## 1. System
|
||||
|
||||
| # | Method | Path | Description |
|
||||
@@ -33,11 +35,14 @@ owner: "Warren"
|
||||
| 7 | GET | `/api/v1/stats/inference` | LLM/Embedding health |
|
||||
| 8 | POST | `/api/v1/config/cache` | Toggle Redis cache |
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
GET /health
|
||||
→ {"status":"ok","version":"1.0.0","uptime_ms":248233}
|
||||
curl http://localhost:3002/health
|
||||
```
|
||||
```json
|
||||
{"status":"ok","version":"1.0.0","uptime_ms":7052517}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. File Management
|
||||
|
||||
@@ -54,12 +59,25 @@ GET /health
|
||||
| 17 | GET | `/api/v1/progress/:file_uuid` | Processing progress |
|
||||
| 18 | GET | `/api/v1/jobs` | Monitor jobs (filterable) |
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
POST /api/v1/files/register
|
||||
{"file_path":"/sftpgo/data/demo/video.mp4"}
|
||||
→ {"success":true,"file_uuid":"3abeee81...","duration":5954.0}
|
||||
curl -X POST http://localhost:3002/api/v1/files/register \
|
||||
-H "X-API-Key: muser_test_apikey" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"file_path":"/sftpgo/data/demo/video.mp4"}'
|
||||
```
|
||||
```json
|
||||
{"success":true,"file_uuid":"3abeee81d94597629ed8cb943f182e94","duration":5954.0}
|
||||
```
|
||||
|
||||
```bash
|
||||
curl "http://localhost:3002/api/v1/files?page=1&page_size=2" \
|
||||
-H "X-API-Key: muser_test_apikey"
|
||||
```
|
||||
```json
|
||||
{"files":[{"file_name":"Charade (1963)..."},{"file_name":"view13.mp4"}],"total":37}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Search
|
||||
|
||||
@@ -74,12 +92,27 @@ POST /api/v1/files/register
|
||||
| 25 | POST | `/api/v1/search/universal` | BM25 keyword (requires file_uuid) |
|
||||
| 26 | POST | `/api/v1/search/frames` | Frame-level search |
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
POST /api/v1/search/universal
|
||||
{"query":"friends","mode":"bm25","file_uuid":"3abeee81..."}
|
||||
→ {"count":1,"results":[{"text":"You won't find it difficult..."}]}
|
||||
curl -X POST http://localhost:3002/api/v1/search/universal \
|
||||
-H "X-API-Key: muser_test_apikey" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"query":"name","limit":2,"mode":"bm25","uuid":"3abeee81d94597629ed8cb943f182e94"}'
|
||||
```
|
||||
```json
|
||||
{"count":1,"results":[{"text":"What's your name?","score":0.90}]}
|
||||
```
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3002/api/v1/search/universal \
|
||||
-H "X-API-Key: muser_test_apikey" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"query":"friends","limit":2,"mode":"bm25","uuid":"3abeee81d94597629ed8cb943f182e94"}'
|
||||
```
|
||||
```json
|
||||
{"count":1,"results":[{"text":"You won't find it difficult to make some new friends.","score":0.90}]}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Face Trace
|
||||
|
||||
@@ -88,18 +121,43 @@ POST /api/v1/search/universal
|
||||
| 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) |
|
||||
|
||||
**Parameters:**
|
||||
### sortby — list traces
|
||||
|
||||
Parameters:
|
||||
- `sort_by`: `face_count` | `duration` | `first_appearance`
|
||||
- `min_faces`, `min_confidence`, `max_confidence`: filters
|
||||
- `interpolate=true`: fills sparse gaps with lerp bbox
|
||||
- `limit`: max results
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
POST /api/v1/file/3abeee81.../face_trace/sortby
|
||||
{"sort_by":"face_count","limit":3}
|
||||
→ {"total_traces":6892,"total_faces":108204,
|
||||
"traces":[{"trace_id":3128,"face_count":1109}]}
|
||||
curl -X POST "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/face_trace/sortby" \
|
||||
-H "X-API-Key: muser_test_apikey" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"sort_by":"face_count","limit":2}'
|
||||
```
|
||||
```json
|
||||
{"success":true,"total_traces":6892,"total_faces":108204,"traces":[
|
||||
{"trace_id":3128,"face_count":1109,"avg_confidence":0.779},
|
||||
{"trace_id":3126,"face_count":743,"avg_confidence":0.758}
|
||||
]}
|
||||
```
|
||||
|
||||
### trace/:trace_id/faces — individual detections
|
||||
|
||||
Parameters:
|
||||
- `limit`, `offset`: pagination
|
||||
- `interpolate`: boolean (fills sparse gaps with lerp bbox)
|
||||
|
||||
```bash
|
||||
curl "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/trace/2/faces?limit=2&interpolate=true" \
|
||||
-H "X-API-Key: muser_test_apikey"
|
||||
```
|
||||
```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}
|
||||
]}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Media
|
||||
|
||||
@@ -110,6 +168,20 @@ POST /api/v1/file/3abeee81.../face_trace/sortby
|
||||
| 31 | GET | `/api/v1/file/:file_uuid/video/bbox` | Bbox overlay (?start=&end=&duration=) |
|
||||
| 32 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | Trace clip (?padding=) |
|
||||
|
||||
```bash
|
||||
curl -o thumb.jpg "http://localhost:3002/api/v1/file/3abeee81.../thumbnail?frame=4650" \
|
||||
-H "X-API-Key: muser_test_apikey"
|
||||
```
|
||||
Returns JPEG binary (82KB, 1920×1080).
|
||||
|
||||
```bash
|
||||
curl -o trace_clip.mp4 "http://localhost:3002/api/v1/file/3abeee81.../trace/2/video" \
|
||||
-H "X-API-Key: muser_test_apikey"
|
||||
```
|
||||
Returns MP4 video binary (3.0MB) with bbox overlay.
|
||||
|
||||
---
|
||||
|
||||
## 6. Identities
|
||||
|
||||
| # | Method | Path | Description |
|
||||
@@ -123,11 +195,27 @@ POST /api/v1/file/3abeee81.../face_trace/sortby
|
||||
| 39 | GET | `/api/v1/identity/:identity_uuid/chunks` | Chunks for identity |
|
||||
| 40 | GET | `/api/v1/faces/candidates` | Unbound face gallery |
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
GET /api/v1/identities?page=1&page_size=5
|
||||
→ {"identities":[{"name":"Cary Grant","tmdb_id":...}]}
|
||||
curl "http://localhost:3002/api/v1/identities?page=1&page_size=3" \
|
||||
-H "X-API-Key: muser_test_apikey"
|
||||
```
|
||||
```json
|
||||
{"identities":[
|
||||
{"name":"Cary Grant","tmdb_id":2102},
|
||||
{"name":"Audrey Hepburn","tmdb_id":187},
|
||||
{"name":"Walter Matthau","tmdb_id":2091}
|
||||
]}
|
||||
```
|
||||
|
||||
```bash
|
||||
curl "http://localhost:3002/api/v1/faces/candidates?page=1&page_size=2" \
|
||||
-H "X-API-Key: muser_test_apikey"
|
||||
```
|
||||
```json
|
||||
{"total":42,"candidates":[{"frame_number":30,"confidence":0.85},...]}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Identity Binding
|
||||
|
||||
@@ -137,12 +225,17 @@ GET /api/v1/identities?page=1&page_size=5
|
||||
| 42 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity |
|
||||
| 43 | POST | `/api/v1/identity/:from_uuid/mergeinto` | Merge two identities |
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
POST /api/v1/identity/a9a90105.../bind
|
||||
{"file_uuid":"3abeee81...","face_id":"face_42"}
|
||||
→ {"success":true}
|
||||
curl -X POST "http://localhost:3002/api/v1/identity/a9a90105-6d6b-46ff-92da-0c3c1a57dff4/bind" \
|
||||
-H "X-API-Key: muser_test_apikey" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"file_uuid":"3abeee81d94597629ed8cb943f182e94","face_id":"face_42"}'
|
||||
```
|
||||
```json
|
||||
{"success":true}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Resources
|
||||
|
||||
@@ -152,6 +245,16 @@ POST /api/v1/identity/a9a90105.../bind
|
||||
| 45 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat |
|
||||
| 46 | GET | `/api/v1/resources` | List all resources |
|
||||
|
||||
```bash
|
||||
curl "http://localhost:3002/api/v1/resources" \
|
||||
-H "X-API-Key: muser_test_apikey"
|
||||
```
|
||||
```json
|
||||
{"resources":[{"resource_id":"mxbai-embed-large-v1","resource_type":"embedding_model"}]}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Agents — 5W1H
|
||||
|
||||
| # | Method | Path | Description |
|
||||
@@ -161,6 +264,18 @@ POST /api/v1/identity/a9a90105.../bind
|
||||
| 49 | POST | `/api/v1/agents/5w1h/batch` | Batch analysis |
|
||||
| 50 | GET | `/api/v1/agents/5w1h/status` | Job status |
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:3002/api/v1/agents/translate" \
|
||||
-H "X-API-Key: muser_test_apikey" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"text":"Hello world","target_language":"zh-TW"}'
|
||||
```
|
||||
```json
|
||||
{"success":true,"translated_text":"你好世界"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Agents — Identity
|
||||
|
||||
| # | Method | Path | Description |
|
||||
|
||||
Reference in New Issue
Block a user