From 6c266f0beb779ebcd3f8f20cc7917a0497721c3f Mon Sep 17 00:00:00 2001 From: Warren Date: Fri, 8 May 2026 04:28:17 +0800 Subject: [PATCH] docs: add real curl examples with verified responses --- .../RELEASE/RELEASE_API_REFERENCE_v1.0.0.md | 167 +++++++++++++++--- 1 file changed, 141 insertions(+), 26 deletions(-) diff --git a/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_v1.0.0.md b/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_v1.0.0.md index fd27533..a7089ae 100644 --- a/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_v1.0.0.md +++ b/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_v1.0.0.md @@ -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: ` (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 |