docs: fix API_REFERENCE key to official format

2026-05-08 09:55:34 +08:00
parent f122a1ebca
commit 653387a557
1 changed files with 304 additions and 0 deletions
--- 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
@@ -0,0 +1,304 @@
+---
+document_type: "reference_doc"
+service: "MOMENTRY_CORE"
+title: "Momentry Core Release API Reference v1.0.0"
+date: "2026-05-08"
+version: "V4.0"
+status: "active"
+owner: "Warren"
+---
+
+# Momentry Core API Reference v1.0.0
+
+56 endpoints across 10 categories, with real curl examples and responses.
+
+## Base
+
+| Environment | URL |
+|-------------|-----|
+| Production | `$BASE` or `https://api.momentry.ddns.net` |
+| Development | `http://localhost:3003` |
+| Auth | Header `X-API-Key: <key>` (login endpoint unprotected) |
+
+### Quick Setup (copy-paste once)
+
+```bash
+BASE=http://localhost:3002
+KEY="X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
+FILE=3abeee81d94597629ed8cb943f182e94
+```
+
+All curl examples below use `$BASE`, `$KEY`, `$FILE`. After running the setup above, you can copy-paste each example directly.
+
+---
+
+## 1. System
+
+| # | Method | Path | Description |
+|---|--------|------|-------------|
+| 1 | GET | `/health` | Server status (ok/degraded) |
+| 2 | GET | `/health/detailed` | Per-service health + latency |
+| 3 | POST | `/api/v1/auth/login` | Username/password → API key |
+| 4 | POST | `/api/v1/auth/logout` | Invalidate session |
+| 5 | GET | `/api/v1/stats/ingest` | Ingest statistics |
+| 6 | GET | `/api/v1/stats/sftpgo` | SFTPGo status |
+| 7 | GET | `/api/v1/stats/inference` | LLM/Embedding health |
+| 8 | POST | `/api/v1/config/cache` | Toggle Redis cache |
+
+```bash
+curl $BASE/health
+```
+```json
+{"status":"ok","version":"1.0.0","uptime_ms":7052517}
+```
+
+---
+
+## 2. File Management
+
+| # | Method | Path | Description |
+|---|--------|------|-------------|
+| 9 | POST | `/api/v1/files/register` | Register video → file_uuid |
+| 10 | POST | `/api/v1/unregister` | Delete file + all data |
+| 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/chunks` | List pre-chunks |
+| 17 | GET | `/api/v1/progress/:file_uuid` | Processing progress |
+| 18 | GET | `/api/v1/jobs` | Monitor jobs (filterable) |
+
+```bash
+curl -X POST $BASE/api/v1/files/register \
+  -H "$KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"file_path":"/sftpgo/data/demo/video.mp4"}'
+```
+```json
+{"success":true,"file_uuid":"$FILE","duration":5954.0}
+```
+
+```bash
+curl "$BASE/api/v1/files?page=1&page_size=2" -H "$KEY"
+```
+```json
+{"files":[{"file_name":"Charade (1963)..."}],"total":37}
+```
+
+---
+
+## 3. Search
+
+| # | 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 |
+
+```bash
+curl -X POST $BASE/api/v1/search/universal \
+  -H "$KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"name","limit":2,"mode":"bm25","uuid":"$FILE"}'
+```
+```json
+{"count":1,"results":[{"text":"What's your name?","score":0.90}]}
+```
+
+```bash
+curl -X POST $BASE/api/v1/search/universal \
+  -H "$KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"friends","limit":2,"mode":"bm25","uuid":"$FILE"}'
+```
+```json
+{"count":1,"results":[{"text":"You won't find it difficult to make some new friends.","score":0.90}]}
+```
+
+---
+
+## 4. Face Trace
+
+| # | 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) |
+
+### sortby — list traces
+
+Parameters:
+- `sort_by`: `face_count` | `duration` | `first_appearance`
+- `min_faces`, `min_confidence`, `max_confidence`: filters
+- `limit`: max results
+
+```bash
+curl -X POST "$BASE/api/v1/file/$FILE/face_trace/sortby" \
+  -H "$KEY" \
+  -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 "$BASE/api/v1/file/$FILE/trace/2/faces?limit=2&interpolate=true" \
+  -H "$KEY"
+```
+```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
+
+| # | 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=&end=) |
+| 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 "$BASE/api/v1/file/$FILE/thumbnail?frame=4650" \
+  -H "$KEY"
+```
+Returns JPEG binary (82KB, 1920×1080).
+
+```bash
+curl -o trace_clip.mp4 "$BASE/api/v1/file/$FILE/trace/2/video" \
+  -H "$KEY"
+```
+Returns MP4 video binary (3.0MB) with bbox overlay.
+
+---
+
+## 6. Identities
+
+| # | Method | Path | Description |
+|---|--------|------|-------------|
+| 33 | GET | `/api/v1/identities` | List all identities |
+| 34 | GET | `/api/v1/file/:file_uuid/identities` | Identities in a file |
+| 35 | POST | `/api/v1/identity` | Register new identity |
+| 36 | GET | `/api/v1/identity/:identity_uuid` | Identity detail |
+| 37 | DELETE | `/api/v1/identity/:identity_uuid` | Delete identity |
+| 38 | GET | `/api/v1/identity/:identity_uuid/files` | Files for identity |
+| 39 | GET | `/api/v1/identity/:identity_uuid/chunks` | Chunks for identity |
+| 40 | GET | `/api/v1/faces/candidates` | Unbound face gallery |
+
+```bash
+curl "$BASE/api/v1/identities?page=1&page_size=3" \
+  -H "$KEY"
+```
+```json
+{"identities":[
+  {"name":"Cary Grant","tmdb_id":2102},
+  {"name":"Audrey Hepburn","tmdb_id":187},
+  {"name":"Walter Matthau","tmdb_id":2091}
+]}
+```
+
+```bash
+curl "$BASE/api/v1/faces/candidates?page=1&page_size=2" \
+  -H "$KEY"
+```
+```json
+{"total":42,"candidates":[{"frame_number":30,"confidence":0.85},...]}
+```
+
+---
+
+## 7. Identity Binding
+
+| # | 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/:from_uuid/mergeinto` | Merge two identities |
+
+```bash
+curl -X POST "$BASE/api/v1/identity/a9a90105-6d6b-46ff-92da-0c3c1a57dff4/bind" \
+  -H "$KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"file_uuid":"$FILE","face_id":"face_42"}'
+```
+```json
+{"success":true}
+```
+
+---
+
+## 8. Resources
+
+| # | 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 |
+
+```bash
+curl "$BASE/api/v1/resources" \
+  -H "$KEY"
+```
+```json
+{"resources":[{"resource_id":"mxbai-embed-large-v1","resource_type":"embedding_model"}]}
+```
+
+---
+
+## 9. Agents — 5W1H
+
+| # | 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 |
+
+```bash
+curl -X POST "$BASE/api/v1/agents/translate" \
+  -H "$KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"text":"Hello world","target_language":"zh-TW"}'
+```
+```json
+{"success":true,"translated_text":"你好世界"}
+```
+
+---
+
+## 10. Agents — Identity
+
+| # | 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 |
+
+---
+
+## Related
+
+- `API_DICTIONARY_V1.0.0.md` — Quick reference (56 endpoints)
+- `API_DOCUMENTATION_v1.0.0.md` — Detailed spec with examples
+- `TRACE/TRACE_API_REFERENCE_V1.0.0.md` — Trace-specific reference