Momentry Studio
5951aca086
Core Changes: - Fix SearchView to use start_frame/end_frame directly (no time*fps conversion) - Add hard_delete support to delete_trace API - VideoPlayer: Main timeline + Mark system foundation - Proxy: Add local routes for auth, media, identity-matches, cluster-results - Add .gitignore to exclude build artifacts and dependencies Design Documents: - Multi-track Mark system design (.opencode/plans/) - Video editing positioning standards research Files Modified: - src/views/SearchView.vue: Frame positioning, ensureMinDuration (240 frames) - src/views/PeopleView.vue: batchDeleteGroups with hard_delete - src/api/index.ts: delete_trace with hard_delete body - src/components/VideoPlayer.vue: Timeline + Mark UI - src-tauri/src/proxy.rs: New local routes - AGENTS.md: Update documentation
434 lines
13 KiB
Markdown
434 lines
13 KiB
Markdown
# Momentry Studio Core API 使用說明
|
||
|
||
本文檔整理 Momentry Studio 使用的 Core API 端點及其使用時機。
|
||
|
||
**Core API 地址**: `http://localhost:3002`
|
||
**API Key**: 透過 `api_key` query parameter 注入（由 Rust proxy 自動處理）
|
||
|
||
---
|
||
|
||
## 一、搜尋相關 API
|
||
|
||
### 1.1 智能搜尋
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/search/llm-smart` | POST | LLM 智能搜尋，結合關鍵字和語意搜尋 |
|
||
| `/api/v1/search/keyword` | POST | 純關鍵字搜尋 |
|
||
| `/api/v1/search/semantic` | POST | 純語意搜尋（向量相似度） |
|
||
| `/api/v1/agents/search` | POST | Agent 搜尋（支援多輪對話） |
|
||
|
||
**使用時機**:
|
||
- `llm-smart`: 搜尋頁面預設搜尋
|
||
- `keyword`: 快速關鍵字匹配
|
||
- `semantic`: 概念搜尋
|
||
- `agents/search`: 搜尋頁面對話模式（支援 `conversation_id` 多輪對話）
|
||
|
||
**Request Body**:
|
||
```json
|
||
{
|
||
"query": "搜尋詞",
|
||
"limit": 20
|
||
}
|
||
```
|
||
|
||
**Response**: 搜尋結果陣列，每個結果包含 `file_uuid`, `start_time`, `end_time`, `start_frame`, `end_frame`, `summary`, `similarity`
|
||
|
||
---
|
||
|
||
### 1.2 人物搜尋
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/identities/search` | GET | 搜尋人物名稱 |
|
||
|
||
**使用時機**: 在人物詳情頁面搜尋要合併的目標人物
|
||
|
||
**Query Params**: `q` (搜尋詞), `limit`
|
||
|
||
---
|
||
|
||
## 二、檔案管理 API
|
||
|
||
### 2.1 檔案列表與詳情
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/files/scan` | GET | 掃描目錄，取得檔案列表 |
|
||
| `/api/v1/file/:uuid` | GET | 取得檔案詳情（fps, duration, width, height 等） |
|
||
| `/api/v1/file/:uuid/processor-counts` | GET | 取得檔案的處理器計數統計 |
|
||
|
||
**使用時機**:
|
||
- `files/scan`: 檔案庫頁面載入檔案列表
|
||
- `file/:uuid`: 播放器需要影片參數、縮圖需要原始尺寸
|
||
- `processor-counts`: 檔案詳情頁面顯示處理狀態
|
||
|
||
---
|
||
|
||
### 2.2 檔案註冊與處理
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/files/register` | POST | 註冊檔案到系統 |
|
||
| `/api/v1/file/:uuid/process` | POST | 執行處理器（transcribe, ocr, face 等） |
|
||
| `/api/v1/file/:uuid/checkin` | POST | 檔案入庫（ingest） |
|
||
| `/api/v1/file/:uuid/checkout` | POST | 檔案出庫 |
|
||
| `/api/v1/unregister` | POST | 取消註冊檔案 |
|
||
|
||
**使用時機**:
|
||
- `register`: 檔案庫頁面註冊新檔案
|
||
- `process`: 檔案庫頁面觸發處理流程
|
||
- `checkin/checkout`: 檔案版本控制
|
||
- `unregister`: 檔案庫頁面刪除檔案
|
||
|
||
---
|
||
|
||
### 2.3 檔案狀態同步
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/file/:uuid/sync-status` | POST | 從資料庫同步檔案處理狀態 |
|
||
|
||
**使用時機**: 前端 polling 檢查處理中的檔案狀態（每 10 秒）
|
||
|
||
---
|
||
|
||
## 三、媒體 API
|
||
|
||
### 3.1 縮圖
|
||
|
||
| 端點 | 方法 | 說明 | 實作位置 |
|
||
|------|------|------|----------|
|
||
| `/api/v1/file/:uuid/thumbnail` | GET | 取得檔案縮圖 | Core API |
|
||
| `/api/v1/face-thumbnail` | GET | 取得人臉縮圖（含 bbox crop） | **Studio 本地** |
|
||
| `/api/v1/file/thumbnail` | GET | 依路徑取得縮圖（未註冊檔案） | **Studio 本地** |
|
||
|
||
**使用時機**:
|
||
- `file/:uuid/thumbnail`: 搜尋結果縮圖、影片時間軸縮圖
|
||
- `face-thumbnail`: 人物詳情頁面人臉縮圖（含 bbox crop）
|
||
- `file/thumbnail`: 檔案庫頁面未註冊檔案的縮圖
|
||
|
||
**注意**: `face-thumbnail` 由 Studio 本地處理，因為 Core API 不支援 bbox crop
|
||
|
||
---
|
||
|
||
### 3.2 影片串流
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/file/:uuid/video` | GET | 影片串流 |
|
||
|
||
**使用時機**: 搜尋結果播放影片
|
||
|
||
**注意**: Core API 已支援 HTTP Range requests，瀏覽器可透過 `<video>` 元素跳轉播放
|
||
|
||
---
|
||
|
||
### 3.3 影格提取
|
||
|
||
| 端點 | 方法 | 說明 | 實作位置 |
|
||
|------|------|------|----------|
|
||
| `/api/v1/media/frame` | GET | 提取指定影格 | **Studio 本地** |
|
||
|
||
**使用時機**: 人物詳情頁面顯示特定幀的圖片
|
||
|
||
---
|
||
|
||
## 四、人物（Identity）API
|
||
|
||
### 4.1 人物列表
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/identities` | GET | 取得所有人物（分頁） |
|
||
|
||
**使用時機**: 人物頁面載入人物列表
|
||
|
||
**注意**: Studio 使用特殊邏輯（最多 10 頁 × 100 筆）避免 Core API timeout
|
||
|
||
---
|
||
|
||
### 4.2 人物詳情
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/identity/:uuid` | GET | 取得單一人物詳情 |
|
||
| `/api/v1/identity/:uuid/faces` | GET | 取得人物的人臉列表 |
|
||
| `/api/v1/identity/:uuid/traces` | GET | 取得人物的軌跡列表 |
|
||
| `/api/v1/identity/:uuid/files` | GET | 取得人物出現的檔案列表 |
|
||
|
||
**使用時機**:
|
||
- `identity/:uuid`: 人物詳情頁面
|
||
- `faces`: 人物詳情頁面人臉列表
|
||
- `traces`: 人物詳情頁面軌跡列表
|
||
- `files`: 人物詳情頁面檔案列表
|
||
|
||
---
|
||
|
||
### 4.3 人物更新
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/identity/:uuid` | PATCH | 更新人物名稱或 metadata |
|
||
|
||
**使用時機**: 人物詳情頁面編輯名稱、狀態、星號
|
||
|
||
**Request Body**:
|
||
```json
|
||
{
|
||
"name": "新名稱",
|
||
"metadata": {
|
||
"status": "confirmed",
|
||
"starred": true
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.4 人物大頭貼
|
||
|
||
| 端點 | 方法 | 說明 | 實作位置 |
|
||
|------|------|------|----------|
|
||
| `/api/v1/identity/:uuid/profile` | GET | 取得人物大頭貼 | **Studio 本地** |
|
||
| `/api/v1/identity/:uuid/profile-image` | POST | 上傳大頭貼 | Core API |
|
||
| `/api/v1/identity/:uuid/profile-image/from-face` | POST | 從人臉設定大頭貼 | Core API |
|
||
|
||
**使用時機**:
|
||
- `profile`: 人物列表、人物詳情頁面顯示大頭貼（本地檔案系統）
|
||
- `profile-image`: 上傳自訂大頭貼
|
||
- `profile-image/from-face`: 從人臉截圖設定大頭貼
|
||
|
||
**注意**: `profile` 由 Studio 本地處理，讀取 `output/identities/{uuid}/profile.jpg`
|
||
|
||
---
|
||
|
||
### 4.5 人物操作
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/identity/:uuid/bind` | POST | 綁定人臉到人物 |
|
||
| `/api/v1/identity/:uuid/unbind` | POST | 解綁人臉 |
|
||
| `/api/v1/identity/:uuid/mergeinto` | POST | 合併人物到另一個人物 |
|
||
| `/api/v1/identity/:uuid` | DELETE | 刪除人物 |
|
||
|
||
**使用時機**:
|
||
- `bind`: 人物詳情頁面新增人臉
|
||
- `unbind`: 人物詳情頁面移除人臉
|
||
- `mergeinto`: 人物詳情頁面合併兩個人物
|
||
- `delete`: 人物詳情頁面刪除人物
|
||
|
||
---
|
||
|
||
### 4.6 人物建立
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/file/:uuid/pending-person` | POST | 從檔案建立待確認人物 |
|
||
| `/api/v1/identities/pending` | POST | 建立待確認身份 |
|
||
|
||
**使用時機**:
|
||
- `pending-person`: 從軌跡建立新人物
|
||
- `pending`: 從軌跡/人臉建立待確認身份
|
||
|
||
---
|
||
|
||
### 4.7 Undo/Redo
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/identity/:uuid/undo` | POST | 復原人物操作 |
|
||
| `/api/v1/identity/:uuid/redo` | POST | 重做人物操作 |
|
||
| `/api/v1/identity/:uuid/history` | GET | 取得操作歷史 |
|
||
| `/api/v1/identity/:uuid/bind/undo` | POST | 復原綁定操作 |
|
||
| `/api/v1/identity/:uuid/bind/redo` | POST | 重做綁定操作 |
|
||
| `/api/v1/identity/:uuid/bind/history` | GET | 取得綁定操作歷史 |
|
||
| `/api/v1/identity/merge/:mergeId/undo` | POST | 復原合併 |
|
||
| `/api/v1/identity/merge/:mergeId/redo` | POST | 重做合併 |
|
||
| `/api/v1/identity/merge/history` | GET | 取得合併歷史 |
|
||
|
||
**使用時機**: 人物詳情頁面 Undo/Redo 功能
|
||
|
||
---
|
||
|
||
## 五、人臉與軌跡 API
|
||
|
||
### 5.1 人臉候選
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/faces/candidates` | GET | 取得未綁定的人臉候選 |
|
||
|
||
**使用時機**: 人物詳情頁面顯示可綁定的人臉
|
||
|
||
---
|
||
|
||
### 5.2 軌跡管理
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/traces/unassigned` | GET | 取得未分配的軌跡 |
|
||
| `/api/v1/file/:uuid/traces` | POST | 列出檔案的所有軌跡 |
|
||
| `/api/v1/file/:uuid/trace/:traceId` | DELETE | 刪除軌跡 |
|
||
| `/api/v1/file/:uuid/trace/:traceId/restore` | POST | 還原刪除的軌跡 |
|
||
| `/api/v1/file/:uuid/trace/:sourceId/merge/:targetId` | POST | 合併軌跡 |
|
||
|
||
**使用時機**:
|
||
- `unassigned`: 人物詳情頁面顯示未分配軌跡
|
||
- 其他: 軌跡管理功能
|
||
|
||
---
|
||
|
||
### 5.3 軌跡 Profile
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/trace-profile` | GET | 取得軌跡 profile |
|
||
| `/api/v1/trace-profile` | PUT | 更新軌跡 profile |
|
||
| `/api/v1/trace-profile/group` | PUT | 批次更新軌跡 profile |
|
||
|
||
**使用時機**: 軌跡標記、命名
|
||
|
||
---
|
||
|
||
### 5.4 檔案 Identity 列表
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/file/:uuid/identities` | GET | 取得檔案中出現的人物 |
|
||
| `/api/v1/file/:uuid/pending-persons` | GET | 取得檔案的待確認人物 |
|
||
|
||
**使用時機**: 檔案詳情頁面顯示人物列表
|
||
|
||
---
|
||
|
||
## 六、處理器 API
|
||
|
||
### 6.1 執行 Agent
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/file/:uuid/identity-agent` | POST | 執行人物識別 Agent |
|
||
| `/api/v1/file/:uuid/cluster-agent` | POST | 執行軌跡聚類 Agent |
|
||
| `/api/v1/agents/identity/run-for-seed` | POST | 為種子人物執行識別 |
|
||
| `/api/v1/agents/identity/match-from-photo` | POST | 從照片匹配人物 |
|
||
|
||
**使用時機**:
|
||
- `identity-agent`: 檔案庫頁面執行人物識別
|
||
- `cluster-agent`: 檔案庫頁面執行軌跡聚類
|
||
- `run-for-seed`: 為已知人物擴展識別
|
||
- `match-from-photo`: 上傳照片比對人物
|
||
|
||
---
|
||
|
||
### 6.2 處理器結果
|
||
|
||
| 端點 | 方法 | 說明 | 實作位置 |
|
||
|------|------|------|----------|
|
||
| `/api/v1/file/:uuid/face-groups` | GET | 取得人臉分組結果 | Core API |
|
||
| `/api/v1/file/:uuid/json/:processor` | POST | 取得處理器 JSON 輸出 | Core API |
|
||
| `/api/v1/cluster-results` | GET | 取得聚類結果 | Studio proxy |
|
||
| `/api/v1/processor-json` | GET | 取得處理器 JSON | Studio proxy |
|
||
| `/api/v1/identity-matches` | GET | 取得人物匹配結果 | Studio 本地檔案 |
|
||
|
||
**使用時機**:
|
||
- `face-groups`: 取得人臉分組
|
||
- `json/:processor`: 取得特定處理器的輸出（如 ocr, asr）
|
||
- `cluster-results`, `processor-json`, `identity-matches`: QC 頁面
|
||
|
||
---
|
||
|
||
## 七、Profile API
|
||
|
||
### 7.1 檔案 Profile
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/file-profile` | GET | 取得檔案 profile |
|
||
| `/api/v1/file-profile` | PUT | 更新檔案 profile |
|
||
|
||
**使用時機**: 檔案元數據管理
|
||
|
||
---
|
||
|
||
## 八、統計 API
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/progress/:uuid` | POST | 取得處理進度 |
|
||
| `/api/v1/stats/pipeline/:uuid` | GET | 取得 pipeline 統計 |
|
||
| `/api/v1/stats/file/:uuid` | GET | 取得檔案統計 |
|
||
|
||
**使用時機**: 檔案處理進度顯示
|
||
|
||
---
|
||
|
||
## 九、姿勢與外觀 API
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/file/:uuid/pose` | GET | 取得指定幀的姿勢估計 |
|
||
| `/api/v1/file/:uuid/appearance` | GET | 取得指定幀的外觀特徵 |
|
||
|
||
**Query Params**: `frame`, `bbox_x`, `bbox_y`, `bbox_w`, `bbox_h`
|
||
|
||
**使用時機**: 人物詳情頁面顯示姿勢/外觀分析
|
||
|
||
---
|
||
|
||
## 十、其他 API
|
||
|
||
### 10.1 說話者綁定
|
||
|
||
| 端點 | 方法 | 說明 |
|
||
|------|------|------|
|
||
| `/api/v1/file/:uuid/bind-speakers` | POST | 綁定說話者到人物 |
|
||
|
||
**使用時機**: 將語音與人物關聯
|
||
|
||
---
|
||
|
||
### 10.2 本地 API（不經過 Core API）
|
||
|
||
以下 API 由 Studio 本地處理，**不會**轉發到 Core API：
|
||
|
||
| 端點 | 說明 | 資料來源 |
|
||
|------|------|----------|
|
||
| `/api/v1/auth/login` | 本地登入驗證 | SQLite `app_users` 表 |
|
||
| `/api/v1/search-history` | 搜尋歷史 CRUD | SQLite `search_history` 表 |
|
||
| `/api/v1/bookmarks` | 書籤 CRUD | SQLite `bookmarks` 表 |
|
||
| `/api/v1/identity/:uuid/profile` | 人物大頭貼 | 本地檔案系統 |
|
||
| `/api/v1/face-thumbnail` | 人臉縮圖（bbox crop） | Core API + 本地裁切 |
|
||
| `/api/v1/media/frame` | 影格提取 | ffmpeg 本地執行 |
|
||
| `/api/v1/file/thumbnail` | 依路徑縮圖 | ffmpeg 本地執行 |
|
||
| `/api/v1/identity-matches` | 人物匹配結果 | 本地 JSON 檔案 |
|
||
| `/api/v1/cluster-results` | 聚類結果 | Core API `/face-groups` |
|
||
| `/api/v1/processor-json` | 處理器 JSON | Core API `/json/:processor` |
|
||
|
||
---
|
||
|
||
## 十一、已知問題與改進建議
|
||
|
||
### 11.1 高畫質影片卡頓
|
||
|
||
**問題**: 4K、10+ Mbps 影片在瀏覽器播放卡頓
|
||
|
||
**建議**: Core API 實作 adaptive bitrate streaming（HLS/DASH）
|
||
|
||
### 11.2 分頁限制
|
||
|
||
**問題**: Core API 在 `per_page >= 100` 時可能 timeout
|
||
|
||
**現行解法**: 前端限制 `perPage <= 20`，`get_people` 使用特殊分頁邏輯
|
||
|
||
---
|
||
|
||
## 十二、API Key 注入
|
||
|
||
所有經由 Rust proxy 轉發的請求都會自動注入 `api_key` query parameter：
|
||
|
||
```
|
||
http://localhost:3002/api/v1/identities?api_key=muser_xxx&page=1&per_page=100
|
||
```
|
||
|
||
前端無需手動處理 API Key，由 proxy.rs 統一管理。 |