---
document_type: "reference_doc"
service: "MOMENTRY_CORE"
title: "Momentry Core API 文件總覽"
date: "2026-04-23"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "momentry"
  - "文件總覽"
  - "core"
ai_query_hints:
  - "查詢 Momentry Core API 文件總覽 的內容"
  - "Momentry Core API 文件總覽 的主要目的是什麼？"
  - "如何操作或實施 Momentry Core API 文件總覽？"
---

# Momentry Core API 文件總覽

> **Version**: 3.0 | **Updated**: 2026-04-23
> **Source**: Generated from actual Rust code (`src/api/`)

---

## 📁 文件結構

```
docs_v1.0/
├── REFERENCE/
│   ├── API_REFERENCE.md      ← 主要 API 參考文件（71 個端點）
│   ├── API_KEY_DESIGN.md     ← API Key 系統設計文件
│   └── API_TRAINING_MARCOM.md ← marcom 團隊教育訓練手冊
├── IMPLEMENTATION/
│   ├── API_EXAMPLES.md       ← 完整範例（curl / n8n / WordPress）
│   ├── API_CURL_EXAMPLES.md  ← curl 快速範例
│   ├── API_WORDPRESS_GUIDE.md ← WordPress 整合指南
│   └── API_N8N_GUIDE.md      ← n8n 整合指南
└── ARCHITECTURE/
    └── API_KEY_ARCHITECTURE.md ← API Key 架構圖
```

---

## 快速選擇指南

| 需求 | 閱讀文件 |
|------|----------|
| **我要查看所有 API 端點** | [API_REFERENCE.md](./API_REFERENCE.md) |
| **我要 curl 範例** | [API_EXAMPLES.md](../IMPLEMENTATION/API_EXAMPLES.md) |
| **我是 marcom 團隊** | [API_TRAINING_MARCOM.md](./API_TRAINING_MARCOM.md) |
| **我要整合 n8n** | [API_N8N_GUIDE.md](../IMPLEMENTATION/API_N8N_GUIDE.md) |
| **我要整合 WordPress** | [API_WORDPRESS_GUIDE.md](../IMPLEMENTATION/API_WORDPRESS_GUIDE.md) |
| **我要了解 API Key 設計** | [API_KEY_DESIGN.md](./API_KEY_DESIGN.md) |

---

## 認證

### 使用方式

```bash
export API_KEY="your_api_key_here"
curl -H "X-API-Key: $API_KEY" http://localhost:3002/api/v1/videos
```

### 環境

| 環境 | URL | 使用時機 |
|------|-----|----------|
| **本地開發** | `http://localhost:3002` | 開發/測試 |
| **Playground** | `http://localhost:3003` | 開發測試（dev 模式） |
| **外部訪問** | `https://api.momentry.ddns.net` | n8n、WordPress、遠端 |

---

## API 端點總覽

| 類別 | 端點數 | 說明 |
|------|--------|------|
| Health & Stats | 5 | 健康檢查與統計（公開） |
| Core Asset | 6 | 影片註冊、查詢、進度 |
| Processing | 7 | 探針、處理、任務 |
| Search | 7 | 向量、BM25、混合搜索 |
| Visual Chunk | 5 | 視覺分片搜索 |
| Face Recognition | 7 | 人臉識別 |
| Person Identity | 21 | 人物身份管理 |
| Global Identities | 6 | 全局身份 |
| Identity Binding | 6 | 身份綁定 |
| Configuration | 1 | 緩存配置 |
| **Total** | **71** | **可達端點** |

### ⚠️ 未掛載端點

以下端點已定義但**未在 router 中掛載**：

| 端點 | 定義位置 |
|------|----------|
| `/api/v1/search/universal` | `universal_search.rs` |
| `/api/v1/search/frames` | `universal_search.rs` |
| `/api/v1/search/persons` | `universal_search.rs` |
| `/api/v1/who` | `who.rs` |
| `/api/v1/who/candidates` | `who.rs` |

---

## 常見問題

### Q: API 返回 401 錯誤？
API Key 無效或過期。請檢查 `X-API-Key` header。

### Q: API 返回 502 錯誤？
```bash
# 檢查服務狀態
launchctl list | grep momentry.api

# 重啟服務
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
```

---

## 相關文件

- [API_REFERENCE.md](./API_REFERENCE.md) - 完整 API 參考
- [INSTALL_MOMENTRY_API.md](../IMPLEMENTATION/INSTALL_MOMENTRY_API.md) - 安裝指南
- [API_KEY_DESIGN.md](./API_KEY_DESIGN.md) - API Key 設計