---
document_type: "reference_doc"
service: "MOMENTRY_CORE"
title: "Momentry Core Release API 參考文件 V1.0.0"
date: "2026-05-03"
version: "V4.0"
status: "outdated"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "api"
  - "reference"
  - "release"
  - "v1.0.0"
  - "marcom"
  - "production"
ai_query_hints:
  - "Momentry Core Release API 完整列表"
  - "API 認證方式與 Base URL（port 3002）"
  - "檔案註冊、處理、搜尋、臉部綁定流程"
  - "錯誤回應格式（401/400/404）"
related_documents:
  - "RELEASE/RELEASE_VERIFICATION_V1.0.0.md"
  - "RELEASE/PRODUCTION_VERIFICATION_V1.0.0.md"
---

# Momentry Core Release API 參考文件 V1.0.0

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-05-03 |
| 文件版本 | V4.0 |
| Base URL | `http://localhost:3002` |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V4.0 | 2026-05-03 | Release 版本：完整 78 端點 API 參考文件 | OpenCode | deepseek-chat |

---

## 認證方式

- **Header**: `X-API-Key: <your_api_key>`
- 未提供或無效的 key 回傳 `401 Unauthorized`
- 所有端點（除 `/health` 與 `/health/detailed` 外）都需要 API key

---

## 錯誤回應格式

```json
// 401 Unauthorized
{ "error": "Unauthorized", "message": "Invalid or missing API key" }

// 400 Bad Request
{ "error": "Bad Request", "message": "Missing required field: file_path" }

// 404 Not Found
{ "error": "Not Found", "message": "Video not found: <uuid>" }
```

---

## 端點列表

### 1. 系統與認證

| # | Method | Path | 說明 |
|---|--------|------|------|
| 1 | GET | `/health` | 系統健康檢查（無需 API key） |
| 2 | GET | `/health/detailed` | 詳細健康狀態（無需 API key） |
| 3 | POST | `/api/v1/auth/login` | 登入 |
| 4 | POST | `/api/v1/auth/logout` | 登出 |

### 2. 檔案管理

| # | Method | Path | 說明 |
|---|--------|------|------|
| 5 | GET | `/api/v1/files` | 檔案列表 |
| 6 | GET | `/api/v1/files/:uuid` | 檔案詳細資訊 |
| 7 | GET | `/api/v1/files/scan` | 掃描目錄中的新檔案 |
| 8 | POST | `/api/v1/files/register` | 註冊檔案 |
| 9 | POST | `/api/v1/unregister` | 取消註冊檔案 |
| 10 | GET | `/api/v1/files/:file_uuid/probe` | 探測檔案資訊（ffprobe） |
| 11 | POST | `/api/v1/files/:file_uuid/process` | 啟動處理 pipeline |
| 12 | GET | `/api/v1/assets/:uuid/status` | 資產處理狀態 |
| 13 | GET | `/api/v1/progress/:uuid` | 處理進度查詢 |
| 14 | GET | `/api/v1/videos/:uuid/details` | 影片詳細資料（含 chunks/pre_chunks） |
| 15 | GET | `/api/v1/videos/:uuid/pre_chunks` | 影片 pre_chunks 列表 |
| 16 | DELETE | `/api/v1/videos/:uuid` | 刪除影片 |

### 3. 任務與佇列

| # | Method | Path | 說明 |
|---|--------|------|------|
| 17 | GET | `/api/v1/jobs` | 任務列表 |
| 18 | GET | `/api/v1/jobs/:job_id` | 任務狀態 |
| 19 | GET | `/api/v1/rules/:rule/status` | Rule 處理狀態 |

### 4. 搜尋

| # | Method | Path | 說明 |
|---|--------|------|------|
| 20 | POST | `/api/v1/search` | 全文搜尋 |
| 21 | POST | `/api/v1/search/hybrid` | 混合搜尋（向量 + BM25） |
| 22 | POST | `/api/v1/search/bm25` | BM25 全文檢索 |
| 23 | POST | `/api/v1/search/universal` | 通用搜尋 |
| 24 | POST | `/api/v1/smart` | 智慧搜尋（多輪對話） |
| 25 | POST | `/api/v1/search/visual` | 視覺搜尋 |
| 26 | POST | `/api/v1/search/visual/class` | 視覺分類搜尋（依物件類別） |
| 27 | POST | `/api/v1/search/visual/density` | 視覺密度搜尋 |
| 28 | POST | `/api/v1/search/visual/stats` | 視覺統計 |
| 29 | POST | `/api/v1/search/visual/combination` | 視覺組合搜尋 |
| 30 | POST | `/api/v1/search/frames` | 影格搜尋 |
| 31 | GET | `/api/v1/search/persons` | 人物搜尋 |
| 32 | GET | `/api/v1/lookup` | UUID 查詢 |

### 5. 身份（Identity）

| # | Method | Path | 說明 |
|---|--------|------|------|
| 33 | GET | `/api/v1/identities` | 身份列表 |
| 34 | GET | `/api/v1/identities/:uuid` | 身份詳細資訊 |
| 35 | GET | `/api/v1/identities/:uuid/files` | 身份相關檔案 |
| 36 | GET | `/api/v1/identities/:uuid/chunks` | 身份相關 chunks |
| 37 | POST | `/api/v1/identities/bind` | 綁定身份 |
| 38 | POST | `/api/v1/identities/unbind` | 解除綁定 |
| 39 | POST | `/api/v1/identities/suggest-av` | 建議音視綁定 |
| 40 | POST | `/api/v1/identities/from-face` | 從臉部建立身份 |
| 41 | POST | `/api/v1/identities/from-person` | 從人物建立身份 |
| 42 | GET | `/api/v1/identity/:binding_type/:binding_value` | 依 binding 查詢身份 |

### 6. 臉部（Face）

| # | Method | Path | 說明 |
|---|--------|------|------|
| 43 | GET | `/api/v1/faces/candidates` | 臉部候選列表 |
| 44 | POST | `/api/v1/face/recognize` | 臉部辨識 |
| 45 | POST | `/api/v1/face/register` | 註冊臉部 |
| 46 | POST | `/api/v1/face/search` | 臉部搜尋 |
| 47 | GET | `/api/v1/face/list` | 臉部列表 |
| 48 | GET | `/api/v1/face/results/:file_uuid` | 臉部辨識結果 |
| 49 | GET | `/api/v1/files/:file_uuid/faces/:face_id` | 臉部詳細資訊 |
| 50 | DELETE | `/api/v1/files/:file_uuid/faces/:face_id` | 刪除臉部 |
| 51 | GET | `/api/v1/files/:file_uuid/faces/:face_id/thumbnail` | 臉部縮圖 |

### 7. 信號（Signal）

| # | Method | Path | 說明 |
|---|--------|------|------|
| 52 | GET | `/api/v1/signals/unbound` | 未綁定信號列表 |
| 53 | GET | `/api/v1/signals/:uuid/:binding_type/:binding_value/timeline` | 信號時間軸 |

### 8. 檔案身份關聯

| # | Method | Path | 說明 |
|---|--------|------|------|
| 54 | GET | `/api/v1/files/:uuid/identities` | 檔案的身份列表 |

### 9. 快照（Snapshot）

| # | Method | Path | 說明 |
|---|--------|------|------|
| 55 | GET | `/api/v1/files/:uuid/snapshots` | 取得檔案快照 |
| 56 | POST | `/api/v1/files/:uuid/snapshots` | 產生檔案快照 |
| 57 | GET | `/api/v1/files/:uuid/snapshots/status` | 快照處理狀態 |
| 58 | POST | `/api/v1/files/:uuid/snapshots/migrate` | 遷移快照 |
| 59 | POST | `/api/v1/files/:uuid/snapshots/teardown` | 刪除快照 |
| 60 | GET | `/api/v1/identities/:uuid/snapshots` | 取得身份快照 |
| 61 | POST | `/api/v1/identities/:uuid/snapshots` | 產生身份快照 |

### 10. Agent

| # | Method | Path | 說明 |
|---|--------|------|------|
| 62 | POST | `/api/v1/agents/translate` | 翻譯 Agent |
| 63 | POST | `/api/v1/agents/identity/analyze` | 身份分析 Agent |
| 64 | POST | `/api/v1/agents/identity/suggest` | 身份合併建議 |
| 65 | GET | `/api/v1/agents/identity/status` | 身份 Agent 狀態 |
| 66 | POST | `/api/v1/agents/suggest/clustering` | 聚類建議 |
| 67 | POST | `/api/v1/agents/suggest/merge` | 合併建議 |
| 68 | POST | `/api/v1/agents/5w1h/analyze` | 5W1H 分析 |
| 69 | POST | `/api/v1/agents/5w1h/batch` | 5W1H 批量分析 |
| 70 | GET | `/api/v1/agents/5w1h/status` | 5W1H 狀態 |

### 11. 資源（Resource）

| # | Method | Path | 說明 |
|---|--------|------|------|
| 71 | POST | `/api/v1/resources/register` | 註冊資源 |
| 72 | POST | `/api/v1/resources/heartbeat` | 資源心跳 |
| 73 | GET | `/api/v1/resources` | 資源列表 |

### 12. 統計與設定

| # | Method | Path | 說明 |
|---|--------|------|------|
| 74 | GET | `/api/v1/stats/ingest` | 攝取統計 |
| 75 | GET | `/api/v1/stats/sftpgo` | SFTPGo 狀態 |
| 76 | GET | `/api/v1/stats/inference` | 推理健康狀態 |
| 77 | POST | `/api/v1/config/cache` | 快取切換 |

---

## 端點範例

### GET /health

```bash
curl http://localhost:3002/health
```

```json
{
  "status": "ok",
  "version": "1.0.0 (build: ...)",
  "uptime_ms": 189049
}
```

### POST /api/v1/files/register

```bash
curl -X POST http://localhost:3002/api/v1/files/register \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your_api_key>" \
  -d '{"file_path": "/path/to/video.mp4"}'
```

```json
{
  "success": true,
  "file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
  "file_name": "video.mp4",
  "duration": 120.5,
  "width": 1920,
  "height": 1080,
  "fps": 30.0
}
```

### POST /api/v1/search

```bash
curl -X POST http://localhost:3002/api/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your_api_key>" \
  -d '{"query": "關鍵字", "uuid": "<file_uuid>"}'
```

```json
{
  "results": [
    {
      "chunk_id": "chunk_42",
      "text": "轉錄文字內容",
      "start_time": 12.5,
      "end_time": 15.3,
      "score": 0.89
    }
  ],
  "total": 1
}
```

### GET /api/v1/progress/:uuid

```bash
curl http://localhost:3002/api/v1/progress/<file_uuid> \
  -H "X-API-Key: <your_api_key>"
```

```json
{
  "uuid": "<file_uuid>",
  "overall_progress": 65,
  "processors": [
    {"name": "cut", "status": "completed", "progress": 100},
    {"name": "asr", "status": "running", "progress": 50},
    {"name": "yolo", "status": "pending", "progress": 0}
  ]
}
```

### POST /api/v1/identities/bind

```bash
curl -X POST http://localhost:3002/api/v1/identities/bind \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your_api_key>" \
  -d '{"identity_id": 1, "binding_type": "face", "binding_value": "<face_id>"}'
```

```json
{
  "success": true,
  "message": "Bound face '<face_id>' to Identity '<name>'"
}
```

### GET /api/v1/files/:file_uuid/faces/:face_id/thumbnail

```bash
curl -o thumbnail.jpg http://localhost:3002/api/v1/files/<file_uuid>/faces/<face_id>/thumbnail \
  -H "X-API-Key: <your_api_key>"
```

回傳 JPEG 二進位資料。

### GET /api/v1/identities

```bash
curl "http://localhost:3002/api/v1/identities?page=1&page_size=20" \
  -H "X-API-Key: <your_api_key>"
```

```json
{
  "identities": [
    {"id": 1, "name": "張三", "binding_count": 5}
  ],
  "count": 15
}
```

---

## 常見錯誤

| HTTP 狀態 | 原因 | 解決方式 |
|-----------|------|----------|
| 401 | 缺少或無效的 API key | 確認 header `X-API-Key` 已設定 |
| 400 | 請求參數錯誤 | 檢查必要欄位是否遺漏 |
| 404 | 資源不存在 | 確認 file_uuid / identity_id 是否正確 |
| 500 | 伺服器內部錯誤 | 聯繫系統管理員 |

---

## 重要備註

- `/:uuid` 與 `/:file_uuid` 均為 32 碼 hex string
- Process 為非同步操作，完成後需透過 Progress 端點輪詢
- 搜尋端點回傳結果包含 `score`（0.0~1.0），越高越相關
- 臉部縮圖端點回傳 JPEG binary，非 JSON
