From 047f6c4b2b4672a5b8e149a596de385e130a765c Mon Sep 17 00:00:00 2001
From: Warren <warren@momentry.ddns.net>
Date: Fri, 8 May 2026 12:32:56 +0800
Subject: [PATCH] docs: demo sequence v1.0.0 - curl POST + browser video

---
 docs_v1.0/API_V1.0.0/DEMO_SEQUENCE_v1.0.0.md | 114 +++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 docs_v1.0/API_V1.0.0/DEMO_SEQUENCE_v1.0.0.md

diff --git a/docs_v1.0/API_V1.0.0/DEMO_SEQUENCE_v1.0.0.md b/docs_v1.0/API_V1.0.0/DEMO_SEQUENCE_v1.0.0.md
new file mode 100644
index 0000000..37588e3
--- /dev/null
+++ b/docs_v1.0/API_V1.0.0/DEMO_SEQUENCE_v1.0.0.md
@@ -0,0 +1,114 @@
+# Demo Sequence v1.0.0
+
+Curl for POST, browser for GET/Video.
+
+## Setup
+
+```bash
+KEY="X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
+BASE=https://api.momentry.ddns.net
+FILE=3abeee81d94597629ed8cb943f182e94
+```
+
+---
+
+## 1. Server Alive
+
+Curl:
+```bash
+curl $BASE/health
+```
+
+Browser: open `https://api.momentry.ddns.net/health`
+
+---
+
+## 2. List Traces (top 3 最多臉孔)
+
+Curl:
+```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":3}'
+```
+
+**預期**: 6892 traces, 最大 trace 1109 faces
+
+---
+
+## 3. Trace 詳情 + 補間動畫
+
+Curl:
+```bash
+curl "$BASE/api/v1/file/$FILE/trace/2/faces?limit=3&interpolate=true" -H "$KEY"
+```
+
+**預期**: real + interpolated frames，bbox 線性過渡
+
+---
+
+## 4. BM25 關鍵字搜尋
+
+Curl:
+```bash
+curl -X POST $BASE/api/v1/search/universal -H "$KEY" -H "Content-Type: application/json" -d '{"query":"friends","limit":3,"mode":"bm25","uuid":"$FILE"}'
+```
+
+**預期**: "You won't find it difficult to make some new friends."
+
+---
+
+## 5. 身分列表
+
+Curl:
+```bash
+curl "$BASE/api/v1/identities?page=560&page_size=5" -H "$KEY"
+```
+
+**預期**: Cary Grant, Audrey Hepburn, Walter Matthau...
+
+---
+
+## 6. Trace 影片播放 (Browser)
+
+Browser 開:
+```
+https://api.momentry.ddns.net/api/v1/file/3abeee81d94597629ed8cb943f182e94/trace/3128/video?padding=1
+```
+
+**預期**: MP4 影片，紅框標記臉部，顯示 "t3128" 標籤
+
+---
+
+## 7. BBOX 影片 (frame 區間)
+
+Browser 開:
+```
+https://api.momentry.ddns.net/api/v1/file/3abeee81d94597629ed8cb943f182e94/video/bbox?start=68000&end=69000
+```
+
+**預期**: 該區間內所有臉部偵測的 bbox overlay 影片
+
+---
+
+## 8. Frame 縮圖
+
+Browser 開:
+```
+https://api.momentry.ddns.net/api/v1/file/3abeee81d94597629ed8cb943f182e94/thumbnail?frame=68280
+```
+
+**預期**: JPEG 圖片（trace #3128 的第一幀）
+
+---
+
+## Summary
+
+| Step | Type | Endpoint | What to See |
+|------|------|----------|-------------|
+| 1 | Curl/Browser | `/health` | Server ok |
+| 2 | Curl | `face_trace/sortby` | 6892 traces |
+| 3 | Curl | `trace/:id/faces?interpolate=true` | Interpolated bbox |
+| 4 | Curl | `search/universal` | BM25 match |
+| 5 | Curl | `/identities` | Named persons |
+| 6 | **Browser** | `trace/:id/video` | MP4 with bbox |
+| 7 | **Browser** | `video/bbox` | Frame interval overlay |
+| 8 | **Browser** | `thumbnail` | Single frame JPEG |