---
document_type: "reference_doc"
service: "MOMENTRY_CORE"
title: "Momentry Core API 參考文件 V1.0.0 (Demo 完整指南)"
date: "2026-05-01"
version: "V3.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "api"
  - "reference"
  - "v1.0.0"
  - "demo"
  - "marcom"
ai_query_hints:
  - "查詢 V1.0.0 Demo 所需 API 列表"
  - "Momentry Core Demo 流程如何使用 API？"
  - "API 的檔案註冊、處理、臉部綁定流程"
  - "Demo 流程中 Scan → Unregister → Register → Probe → Process → Faces → Bind 的完整步驟"
  - "API 的 curl 範例與回應格式"
  - "Process 回傳 400 Bad Request 的常見原因與解決方法"
  - "臉部查詢回傳空結果的疑難排解步驟"
related_documents:
  - "STANDARDS/DOCS_STANDARD.md"
  - "API_V1.0.0/MOMENTRY_CORE_API_V1.0.0.md"
  - "TEST_REPORT_CLI.md"
---

# Momentry Core API 參考文件 V1.0.0 (Demo 完整指南)

## 關鍵術語定義

| 術語 | 定義 |
|------|------|
| file_uuid | 32 碼 SHA256 檔案識別碼 |
| X-API-Key | API 認證方式，透過 HTTP Header 傳遞 |
| Scan | 掃描檔案系統，列出所有檔案及當前狀態 |
| Register | 將檔案加入資料庫系統 |
| Probe | 讀取檔案 metadata（時長、解析度、幀率） |
| Bind | 將臉部綁定到指定身份 |
| Progress | 獲取處理進度與目前階段 |

## 📊 文件統計 (Document Statistics)

| 項目 | 數值 |
|---|---|
| **收錄端點** | 15+ (Demo 核心流程) |
| **涵蓋率** | Demo 流程 100% |
| **測試狀態** | ✅ CLI Verified |

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-05-01 |
| 文件版本 | V3.0 |

---

## 1. Demo 流程總覽 (Demo Workflow)

本文件專注於 **Demo 測試計畫** 所需的 API。以下是完整流程與對應 API：

```
1. 掃描狀態 (Scan)       → GET  /api/v1/files/scan
2. 檔案重置 (Unregister)  → POST /api/v1/unregister
3. 檔案註冊 (Register)    → POST /api/v1/files/register
4. 檔案探測 (Probe)      → GET  /api/v1/files/:file_uuid/probe
5. 開始處理 (Process)    → POST /api/v1/files/:file_uuid/process
6. 監控進度 (Progress)   → GET  /api/v1/progress/:file_uuid**
7. 查詢臉部 (Faces)      → GET  /api/v1/faces/candidates
8. 綁定身份 (Bind)       → POST /api/v1/identities/bind
```

---

## 2. 快速資訊

- **Base URL (Dev)**: `http://localhost:3003`
- **Base URL (Prod)**: `http://localhost:3002`
- **認證方式**: Header `X-API-Key: muser_test_001`
- **測試 Key**: `muser_test_001`

---

## 3. API 詳細說明 (依 Demo 順序)

### 3.1 掃描檔案系統 (Scan Files)
**路徑**: `GET /api/v1/files/scan`

**用途**: 列出檔案系統中所有檔案及當前狀態，**是 Demo 流程的第一步**。

**Response**:
```json
{
    "files": [
        {
            "file_name": "A12T3-Share-User Experience of Thunderbolt 3 Shareable Storage.mp4",
            "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/A12T3-Share-User Experience of Thunderbolt 3 Shareable Storage.mp4",
            "file_uuid": "7ab7e25f48b58675e33aca44d15c1ecc",
            "is_registered": true,
            "status": "processing"
        }
    ],
    "total": 20,
    "registered_count": 20,
    "unregistered_count": 0
}
```

---

### 3.2 取消註冊 (Unregister File)
**路徑**: `POST /api/v1/unregister`

**用途**: 從 Scan 結果中選取 `file_uuid`，對該檔案執行取消註冊。

**Request**:
```json
{
    "uuid": "53e3a229bf68878b7a799e811e097f9c"
}
```

**Response**:
```json
{
    "success": true,
    "uuid": "53e3a229bf68878b7a799e811e097f9c",
    "message": "File unregistered successfully"
}
```

---

### 3.3 註冊檔案 (Register File)
**路徑**: `POST /api/v1/files/register`

**用途**: 從 Scan 結果中選取 `file_path`，將檔案加入資料庫系統。

**Request**:
```json
{
    "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/view15.mp4"
}
```

**Response**:
```json
{
    "success": true,
    "file_uuid": "53e3a229bf68878b7a799e811e097f9c",
    "file_name": "view15.mp4",
    "file_path": "/Users/.../demo/view15.mp4",
    "already_exists": false
}
```

---

### 3.4 檔案探測 (Probe File)
**路徑**: `GET /api/v1/files/:file_uuid/probe`

**用途**: 讀取檔案的 metadata (時長、解析度、幀率)。**必須在 Process 前執行**。

**Response**:
```json
{
    "file_uuid": "7ab7e25f48b58675e33aca44d15c1ecc",
    "file_name": "A12T3-Share-User Experience of Thunderbolt 3 Shareable Storage.mp4",
    "duration": 621.55,
    "width": 1920,
    "height": 1080,
    "fps": 29.97,
    "cached": true
}
```

---

### 3.5 觸發處理 (Process File)
**路徑**: `POST /api/v1/files/:file_uuid/process`

**用途**: 啟動後端 Worker 進行分析 (ASR, Face, YOLO, 等)。

**Request**:
```json
{}
```

**Response**:
```json
{
    "success": true,
    "message": "Processing started"
}
```

---

### 3.6 查詢進度 (Progress)
**路徑**: `GET /api/v1/progress/:file_uuid`

**用途**: 獲取處理進度與目前階段。

**Response**:
```json
{
    "file_uuid": "53e3a229bf68878b7a799e811e097f9c",
    "overall_progress": 65,
    "current_processor": "face",
    "status": "running",
    "processors": [
        { "name": "probe", "status": "completed" },
        { "name": "asr", "status": "completed" },
        { "name": "face", "status": "running" }
    ]
}
```

---

### 3.6 查詢未綁定臉部 (List Face Candidates)
**路徑**: `GET /api/v1/faces/candidates`

**用途**: 列出檔案中尚未綁定身份的臉部。

**Query Parameters**:
- `file_uuid` (必填): 檔案 UUID
- `min_confidence` (選填): 最低信心值 (預設 0.5)
- `page_size` (選填): 每頁數量 (預設 20)

**Response**:
```json
{
    "candidates": [
        {
            "id": 123,
            "face_id": "123_RoleA",
            "file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
            "frame_number": 115,
            "confidence": 0.98,
            "bbox": { "x": 50, "y": 50, "w": 100, "h": 100 }
        }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
}
```

---

### 3.7 綁定身份 (Bind Identity)
**路徑**: `POST /api/v1/identities/bind`

**用途**: 將臉部綁定到指定身份 (或建立新身份)。

**Request**:
```json
{
    "identity_id": 22,
    "binding_type": "face",
    "binding_value": "123_RoleA"
}
```

**Response**:
```json
{
    "success": true,
    "message": "Bound face '123_RoleA' to Identity 'Cary Grant'"
}
```

---

## 4. 補充 API (Demo 選用)

### 4.1 列出身份 (List Identities)
**路徑**: `GET /api/v1/identities`

**用途**: 列出系統中所有已建立的身份。

---

## 5. 常見問題 (FAQ)

### Q1: 為什麼 Process 回傳 400 Bad Request？
**Ans**: 必須先執行 **Probe** (`GET /api/v1/files/:file_uuid/probe`)，確保系統已知曉檔案的幀數資訊。

### Q2: 為什麼 Unregister 回傳 404？
**Ans**: 確認伺服器是否已更新至最新版本。舊版可能尚未包含此路由。

### Q3: 臉部查詢回傳空結果？
**Ans**: 
1. 確認檔案已**處理完成** (Progress = 100%)。
2. 嘗試降低 `min_confidence` 參數 (例如設為 0.0)。
3. 確認該檔案內容確實包含可辨識的臉部。

---

## 6. 版本歷史

| 版本 | 日期 | 目的 | 操作人 |
|------|------|------|--------|
| V1.0 | 2026-04-30 | 初始 API 列表 | OpenCode |
| V2.0 | 2026-05-01 | 基於 Production 測試結果補足文件 | OpenCode |
| V3.0 | 2026-05-01 | 重構為 Demo 流程導向，補齊 Probe/Unregister 說明 | OpenCode |
| V3.1 | 2026-05-01 | 修正 `:uuid`→`:file_uuid`，修正 port 3002→3003，移除重複 Scan 章節 | OpenCode |
