Files

M5 28e927f7bb Initial commit: docs_v1.0 structure

- API_V1.0.0: 正式 API 文件（spec、release、deploy、test）
- M4_workspace: M4 工作記錄（review、issue、提案）
- M5_workspace: M5 工作記錄（實作、評估、sync）
- AGENTS.md: 專案規則

M5/M4 協作方式：git push/pull 同步 workspace 文件

2026-05-07 23:42:19 +08:00

3.7 KiB

Raw Blame History

document_type, service, title, date, version, status, owner, created_by, tags, ai_query_hints

document_type

service

title

date

version

status

owner

created_by

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
我要 curl 範例	API_EXAMPLES.md
我是 marcom 團隊	API_TRAINING_MARCOM.md
我要整合 n8n	API_N8N_GUIDE.md
我要整合 WordPress	API_WORDPRESS_GUIDE.md
我要了解 API Key 設計	API_KEY_DESIGN.md

認證

使用方式

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 錯誤？

# 檢查服務狀態
launchctl list | grep momentry.api

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

3.7 KiB Raw Blame History Unescape Escape