---
document_type: "reference_doc"
service: "MOMENTRY_CORE"
title: "Momentry Core V1.0.0 API 參考文件"
date: "2026-04-30"
version: "V1.0"
status: "superseded"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "api"
  - "reference"
  - "v1.0.0"
  - "marcom"
  - "restful"
  - "endpoint"
  - "file-centric"
ai_query_hints:
  - "Momentry Core V1.0.0 API 參考文件的主要內容是什麼？"
  - "查詢 V1.0.0 API 列表包含哪些端點？"
  - "Marcom 團隊如何使用 API Reference？"
  - "API 的 Progressive Workflow 範例"
  - "Momentry API 的檔案管理與搜尋功能"
  - "API 的 Progressive Workflow 操作步驟"
  - "API 的檔案管理與搜尋功能"
related_documents:
  - "STANDARDS/DOCS_STANDARD.md"
  - "DEV_API_V1.0/API_REFERENCE_v1.0.0.md"
  - "API_DICTIONARY_V1.0.0.md"
  - "API_USAGE_DEMO_V1.0.0.md"
  - "PRODUCTION_VERIFICATION_V1.0.0.md"
---

# Momentry Core V1.0.0 API 參考文件

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-30 |
| 文件版本 | V1.0 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-30 | 創建 V1.0.0 API 列表，移除過時端點 | OpenCode | OpenCode |
| V1.1 | 2026-05-06 | 被 DEV_API_REFERENCE_v1.0.0.md 取代（實際路由與此文件有大量差異） | OpenCode | OpenCode |

---

## 關鍵術語定義

| 術語 | 定義 |
|------|------|
| file_uuid | 媒體檔案（影片/圖片/音訊）的唯一 32 碼 SHA256 識別碼 |
| identity_uuid | 全域人物身份識別碼，跨檔案關聯同一人物 |
| Chunk | 可搜尋單位，由 Rule 組合 pre_chunks 產出 |
| Snapshot | 臉部或場景的快取快照，需 migrate 後供 UI 使用 |
| API Key | 認證方式，透過 Header `X-API-Key` 傳遞 |

## 概述

本文檔定義 Momentry Core **V1.0.0** 版本供 **Marcom 團隊** 使用的 API 列表與開發範例。此列表已移除舊版、冗餘及內部使用的端點，確保前端開發使用的是標準且穩定的介面。

---

## 🚀 設計原則 (Design Principles)

### 1. Clear API (介面清晰化)
*   **去蕪存菁**: 嚴格區分 **Public** (公開) 與 **Internal** (內部) 端點。舊版冗餘路徑（如 `/api/v1/videos`, `/api/v1/probe`）已全面移除或合併。
*   **標準化回應**: 所有列表型 API 均回傳統一結構 `{ "success": true, "data": [...], "total": N }`。
*   **命名規範**: 採用 RESTful 風格，資源以複數名詞或明確動作命名（如 `files`, `identities`）。

### 2. File-Centric (以檔案為核心)
*   **唯一識別**: 每個媒體檔案（影片/圖片/音訊）均由 **32 碼 UUID** (`file_uuid`) 唯一標識。
*   **生命週期**: `File` 是所有資料的根節點。所有的 `Chunk` (片段), `Snapshot` (快照), `Jobs` (任務) 皆隸屬於特定的 `File`。
*   **操作模式**: 前端應優先呼叫 `GET /api/v1/files` 取得清單，再透過 `POST /api/v1/files/:uuid/snapshots/migrate` 載入詳細資源。

### 3. Global Identity (全域身份識別)
*   **跨檔案關聯**: `Identity` 代表一個獨立的人物或角色，不受單一檔案限制。
*   **綁定機制 (Binding)**: 透過 `POST /api/v1/identities/bind`，我們可以將多個檔案中偵測到的臉部 (`face`) 或聲音 (`speaker`) 聚合到同一個 `Identity` 下。
*   **資料聚合**: 查詢某個 `Identity` 即可看到該人物在所有歷史檔案中的軌跡 (`/api/v1/identities/:uuid/files`)。

---

## 當前狀態

| 項目 | 狀態 |
|------|------|
| API 版本 | V1.0.0 |
| 開發環境 Port | 3003 |
| 正式環境 Port | 3002 |
| 認證方式 | Header `X-API-Key` |

---

## 1. API Dictionary (端點清單)

### 1.1 系統與認證 (System & Auth)
| Method | Endpoint | 說明 |
| :--- | :--- | :--- |
| `GET` | `/health` | 基本健康檢查 |
| `POST` | `/api/v1/auth/login` | 登入以取得 API Key |

### 1.2 檔案管理 (File Management)
*主要入口：瀏覽與管理資產*
| Method | Endpoint | 說明 |
| :--- | :--- | :--- |
| `GET` | `/api/v1/files` | **列出所有檔案** (支援分頁) |
| `GET` | `/api/v1/files/:uuid` | 取得檔案詳情 (包含 probe_json, metadata) |
| `POST` | `/api/v1/files/register` | 從磁碟註冊新檔案 |
| `DELETE`| `/api/v1/videos/:uuid` | **刪除影片** 及其關聯資料 |

### 1.3 搜尋與檢索 (Search & Retrieval)
| Method | Endpoint | 說明 |
| :--- | :--- | :--- |
| `POST` | `/api/v1/search` | **語意搜尋** (Text-based, 使用 Embedding) |
| `POST` | `/api/v1/search/hybrid` | 混合搜尋 (Vector + BM25 關鍵字) |
| `POST` | `/api/v1/search/visual` | 視覺搜尋 (尋找物件/形狀) |
| `POST` | `/api/v1/search/visual/class`| 依物件類別過濾 (如 "person", "car") |

### 1.4 身份與人物管理 (Identity Management)
*跨影片的人物/角色關聯*
| Method | Endpoint | 說明 |
| :--- | :--- | :--- |
| `GET` | `/api/v1/identities` | **列出所有身份** (人物/角色) |
| `GET` | `/api/v1/identities/:uuid` | 取得身份詳情 (名稱, 品質, 來源) |
| `GET` | `/api/v1/identities/:uuid/files`| 列出該身份出現的所有檔案 |
| `GET` | `/api/v1/identities/:uuid/chunks`| 列出特定的時間軸片段 (Chunks) |
| `POST` | `/api/v1/identities/bind` | 將臉部/聲音訊號綁定至身份 |

### 1.5 臉部與快照 (Face & Snapshots)
| Method | Endpoint | 說明 |
| :--- | :--- | :--- |
| `GET` | `/api/v1/face/list` | 列出特定影片中偵測到的所有臉部 |
| `POST` | `/api/v1/face/recognize` | 對指定影片觸發臉部辨識流程 |
| `GET` | `/api/v1/files/:uuid/snapshots` | 檢查快照快取狀態 (Hot/Cold) |
| `POST` | `/api/v1/files/:uuid/snapshots/migrate`| **載入快照至記憶體** (UI 顯示快圖前需呼叫) |

### 1.6 任務與代理人 (Jobs & Agents)
| Method | Endpoint | 說明 |
| :--- | :--- | :--- |
| `GET` | `/api/v1/progress/:uuid` | 檢查即時處理進度 |
| `POST` | `/api/v1/assets/:uuid/process` | 觸發處理流程 (ASR, YOLO, 等) |
| `POST` | `/api/v1/agents/identity/analyze` | AI Agent: 分析身份重複情況 |

---

## 2. Progressive Workflow Examples (操作範例)

此章節展示典型的使用者操作情境：**尋找影片 → 處理 → 搜尋 → 人物綁定**。

### Phase 1: 瀏覽與檢視
*使用者瀏覽檔案庫以尋找目標影片。*

**Step 1: 登入**
```bash
curl -s -X POST http://localhost:3003/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "demo", "password": "demo"}'
# 回應範例: { "api_key": "muser_test_001..." }
```

**Step 2: 列出檔案**
```bash
curl -s "http://localhost:3003/api/v1/files?page=1&page_size=5" \
  -H "X-API-Key: muser_test_001"
# 回應範例: { "success": true, "data": [ { "file_uuid": "...", "file_name": "Demo.mp4" ... } ] }
```

### Phase 2: 處理與監控
*使用者決定分析該影片的臉部與語音內容。*

**Step 3: 觸發處理**
```bash
curl -s -X POST "http://localhost:3003/api/v1/assets/{file_uuid}/process" \
  -H "X-API-Key: muser_test_001" \
  -H "Content-Type: application/json" \
  -d '{}'
# 啟動 ASR, 臉部偵測等處理器
```

**Step 4: 檢查進度**
```bash
curl -s "http://localhost:3003/api/v1/progress/{file_uuid}" \
  -H "X-API-Key: muser_test_001"
# 回應範例: { "overall_progress": 50, "processors": [...] }
```

### Phase 3: 搜尋內容
*使用者搜尋影片中的特定內容。*

**Step 5: 語意搜尋 (文字描述)**
```bash
curl -s -X POST "http://localhost:3003/api/v1/search" \
  -H "X-API-Key: muser_test_001" \
  -H "Content-Type: application/json" \
  -d '{"query": "一個人拿著紅色的信封", "uuid": "{file_uuid}"}'
# 回應範例: 符合文字描述的片段列表
```

### Phase 4: 身份管理 (GUI 開發重點)
*使用者發現了一張臉，確認該人物，並將其綁定到已知身份。*

**Step 6: 載入快照 (Migrate Snapshots)**
*在 GUI 渲染大量臉部縮圖前，必須先將快取載入記憶體以加速讀取。*
```bash
curl -s -X POST "http://localhost:3003/api/v1/files/{file_uuid}/snapshots/migrate" \
  -H "X-API-Key: muser_test_001" \
  -H "Content-Type: application/json" \
  -d '{"parent_uuid": "{file_uuid}"}'
# 回應範例: { "success": true, "migrated_types": ["faces", ...] }
```

**Step 7: 綁定臉部到身份 (Bind Face)**
*假設偵測到臉部 `face_123`，欲綁定至身份 `uuid_identity`。*
```bash
curl -s -X POST "http://localhost:3003/api/v1/identities/bind" \
  -H "X-API-Key: muser_test_001" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": null,
    "name": "Cary Grant",
    "binding_type": "face",
    "binding_value": "face_123"
  }'
```

---

## 3. 棄用聲明 (Deprecation Notices)

以下端點已在 V1.0.0 移除或棄用，**請勿**在新的開發中使用。

*   `GET /api/v1/videos` (列表) → 已取代為 `GET /api/v1/files`
*   `POST /api/v1/register` → 已取代為 `POST /api/v1/files/register`
*   `POST /api/v1/probe` → 已取代為 `GET /api/v1/files/:uuid`
*   `GET /api/v1/people/...` → 已合併為 `GET /api/v1/identities/...`
*   `/api/v1/n8n/search/...` → 僅供內部 n8n 工作流使用 (請使用標準 `/api/v1/search`)
