momentry_studio/docs/core-api-usage.md

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:

{
  "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:

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