# 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 統一管理。