# Momentry API 使用說明 (curl 範例)

| 項目 | 內容 |
|------|------|
| 版本 | V1.4 |
| 日期 | 2026-03-26 |
| Base URL | `http://localhost:3002` |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.4 | 2026-03-26 | 新增: 任務管理端點 (`/api/v1/jobs`, `/api/v1/jobs/:uuid`)，更新註冊端點回應格式 | OpenCode | deepseek-reasoner |
| V1.3 | 2026-03-25 | 更新: n8n 搜尋回傳 `file_path` 取代 `media_url`，新增 API Key 驗證說明 | OpenCode | deepseek-reasoner |
| V1.2 | 2026-03-23 | 建立 curl 範例文件 | Warren | OpenCode / MiniMax M2.5 |
| V1.1 | 2026-03-18 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |

---

> **狀態說明**:
> - ✅ **已實作**: 健康檢查、搜尋、影片管理端點
> - ⚠️ **規劃中**: API Key 管理功能
> - 🔧 **CLI**: 部分功能需使用命令列工具

---

## 目錄

1. [已實作端點](#1-已實作端點)
2. [API Key 管理](#2-api-key-管理-規劃中)
3. [影片管理](#3-影片管理)
4. [查詢與搜索](#4-查詢與搜索)
5. [系統狀態](#5-系統狀態)

---

## URL 選擇指南

### 兩種 URL 的使用情境

| 環境 | URL | 說明 |
|------|-----|------|
| **本地開發** | `http://localhost:3002` | 直接訪問 API，繞過反向代理 |
| **外部訪問** | `https://api.momentry.ddns.net` | 通過 Caddy 反向代理訪問，需網路可達 |

### 何時使用 localhost:3002

- ✅ 開發/測試環境
- ✅ 直接在伺服器上操作
- ✅ 當 Caddy/反向代理有問題時
- ✅ 需要快速除錯時

### 何時使用 api.momentry.ddns.net

- ✅ n8n workflow 中呼叫 API
- ✅ 外部系統整合
- ✅ 生產環境
- ✅ 從其他機器訪問

### 快速切換範例

```bash
# 本地測試
curl http://localhost:3002/health

# 外部測試（功能相同）
curl https://api.momentry.ddns.net/health
```

### 常見問題

**Q: 為什麼有兩個 URL？**
A: `localhost:3002` 是直接訪問，`api.momentry.ddns.net` 通過 Caddy 反向代理。

**Q: 兩者功能相同嗎？**
A: 是的，所有端點和功能完全相同。

**Q: 502 錯誤時怎麼辦？**
A: 如果 `api.momentry.ddns.net` 返回 502，檢查 Momentry API 服務是否運行：
```bash
launchctl list | grep momentry.api
# 如果未運行
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
```

---

## API 認證

所有 `/api/v1/*` 端點（除了健康檢查）都需要 API Key 認證。請在請求標頭中加入：

```
-H "X-API-Key: YOUR_API_KEY"
```

**目前示範使用的 API Key**: `demo_api_key_12345`

> **注意**: 正式環境請使用安全的 API Key 管理機制。

---

## 1. 已實作端點

### 健康檢查

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

**回應**:
```json
{"status":"ok","version":"0.1.0","uptime_ms":123456}
```

### 詳細健康檢查

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

---

## 2. API Key 管理 *(規劃中)*

> ⚠️ **此功能尚未實作**。以下為規劃中的 API 說明，僅供參考。

### 2.1 建立 API Key

```bash
curl -X POST http://localhost:3002/api/v1/api-keys \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-admin-key" \
  -d '{
    "name": "my-service-key",
    "key_type": "service",
    "permissions": ["read", "write"],
    "ttl_days": 90
  }'
```

### 2.2 列出所有 API Keys

```bash
curl -X GET http://localhost:3002/api/v1/api-keys \
  -H "X-API-Key: your-admin-key"
```

### 2.3 驗證 API Key

```bash
curl -X GET http://localhost:3002/api/v1/api-keys/validate \
  -H "X-API-Key: key-to-validate"
```

### 2.4 撤銷 API Key

```bash
curl -X DELETE http://localhost:3002/api/v1/api-keys/msvc_a1b2c3d4_... \
  -H "X-API-Key: your-admin-key"
```

### 2.5 請求 Key 輪換

```bash
curl -X POST http://localhost:3002/api/v1/api-keys/msvc_a1b2c3d4_.../rotate \
  -H "X-API-Key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "scheduled_rotation"}'
```

### 2.6 取得統計資訊

```bash
curl -X GET http://localhost:3002/api/v1/api-keys/stats \
  -H "X-API-Key: your-admin-key"
```

---

## 3. 影片管理

### 3.1 註冊影片 ✅

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

**回應範例**:

```json
{
  "uuid": "a1b2c3d4e5f6g7h8",
  "video_id": 1,
  "job_id": 123,
  "file_name": "video.mp4",
  "duration": 120.5,
  "width": 1920,
  "height": 1080,
  "already_exists": false
}
```

### 3.2 列出所有影片 ✅

```bash
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/videos
```

### 3.3 查詢影片 ✅

```bash
# 依 UUID 查詢
curl -H "X-API-Key: YOUR_API_KEY" "http://localhost:3002/api/v1/lookup?uuid=a1b2c3d4e5f6g7h8"

# 依路徑查詢
curl -H "X-API-Key: YOUR_API_KEY" "http://localhost:3002/api/v1/lookup?path=/path/to/video.mp4"
```

### 3.4 處理影片 🔧 *(CLI - 非 API)*

影片處理需要使用 CLI 命令：

```bash
# 處理影片（生成 ASR, CUT, YOLO, OCR, Face, Pose 資料）
cargo run --bin momentry -- process <uuid>

# 或處理多個影片
cargo run --bin momentry -- process <uuid1> <uuid2> <uuid3>
```

### 3.5 取得處理進度 ✅

```bash
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/progress/<uuid>
```

**回應範例**:

```json
{
  "uuid": "a1b2c3d4e5f6g7h8",
  "overall_progress": 75,
  "processors": [
    {
      "name": "asr",
      "status": "complete",
      "current": 100,
      "total": 100,
      "progress": 100,
      "message": "7 segments"
    },
    {
      "name": "cut",
      "status": "complete",
      "current": 134,
      "total": 134,
      "progress": 100,
      "message": "134 scenes"
    },
    {
      "name": "yolo",
      "status": "progress",
      "current": 5000,
      "total": 14315,
      "progress": 35,
      "message": "frame 5000"
    }
  ]
}
```

### 3.6 任務管理 ✅

```bash
# 列出所有任務
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/jobs

# 取得特定任務詳情
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/jobs/<uuid>
```

**任務列表回應範例**:
```json
{
  "jobs": [
    {
      "id": 123,
      "uuid": "a1b2c3d4e5f6g7h8",
      "status": "pending",
      "current_processor": null,
      "progress_current": 0,
      "progress_total": 100,
      "created_at": "2026-03-26 10:30:00",
      "started_at": null
    }
  ]
}
```

**任務詳情回應範例**:
```json
{
  "id": 123,
  "uuid": "a1b2c3d4e5f6g7h8",
  "status": "processing",
  "current_processor": "asr",
  "progress_current": 50,
  "progress_total": 100,
  "processors": [
    {
      "processor_type": "asr",
      "status": "complete",
      "started_at": "2026-03-26 10:30:00",
      "completed_at": "2026-03-26 10:35:00",
      "duration_secs": 300.5,
      "error_message": null
    },
    {
      "processor_type": "cut",
      "status": "pending",
      "started_at": null,
      "completed_at": null,
      "duration_secs": null,
      "error_message": null
    }
  ],
  "created_at": "2026-03-26 10:30:00",
  "started_at": "2026-03-26 10:30:00",
  "updated_at": "2026-03-26 10:35:00"
}
```

---

## 4. 查詢與搜索

### 4.1 語意搜尋 ✅

```bash
curl -X POST http://localhost:3002/api/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "query": "測試關鍵字",
    "limit": 5
  }'
```

**回應範例**:

```json
{
  "results": [
    {
      "uuid": "a1b2c3d4e5f6g7h8",
      "chunk_id": "sentence_0006",
      "chunk_type": "sentence",
      "start_time": 48.8,
      "end_time": 55.44,
      "text": "fun plot twists...",
      "score": 0.526
    }
  ],
  "query": "測試關鍵字"
}
```

### 4.2 n8n 格式搜尋 ✅

```bash
curl -X POST http://localhost:3002/api/v1/n8n/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "query": "測試關鍵字",
    "limit": 5
  }'
```

**回應範例**:

```json
{
  "query": "測試關鍵字",
  "count": 2,
  "hits": [
    {
      "id": "c_001",
      "vid": "a1b2c3d4e5f6g7h8",
      "start": 48.8,
      "end": 55.44,
      "title": "Chunk sentence_0006",
      "text": "fun plot twists...",
      "score": 0.92,
      "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"
    }
  ]
}
```

### 4.3 混合搜尋 ✅

```bash
curl -X POST http://localhost:3002/api/v1/search/hybrid \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "query": "測試關鍵字",
    "limit": 5
  }'
```

---

## 5. 系統狀態

### 5.1 健康檢查 ✅

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

**回應**:
```json
{"status":"ok","version":"0.1.0","uptime_ms":123456}
```

### 5.2 詳細健康檢查 ✅

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

**回應範例**:

```json
{
  "status":"ok",
  "version":"0.1.0",
  "uptime_ms":123456,
  "services":{
    "postgres":{"status":"ok","latency_ms":42,"error":null},
    "redis":{"status":"ok","latency_ms":0,"error":null},
    "qdrant":{"status":"ok","latency_ms":15,"error":null}
  }
}
```

---

## 6. n8n Webhook 測試

### 測試 n8n Workflow

**重要**: 測試前請先在 n8n UI 中點擊 "Execute workflow" 按鈕

```bash
# 測試 Video RAG Workflow (Test Mode)
curl -X POST http://localhost:5678/webhook-test/video-rag-mcp \
  -H "Content-Type: application/json" \
  -d '{"query":"charade","limit":3}'

# 帶有 UUID 過濾的搜尋
curl -X POST http://localhost:5678/webhook-test/video-rag-mcp \
  -H "Content-Type: application/json" \
  -d '{"query":"woody","limit":5,"uuid":"a1b10138a6bbb0cd"}'
```

### 生產環境 Webhook

**注意**: 工作流程必須處於 Active 狀態

```bash
curl -X POST http://localhost:5678/webhook/video-rag-mcp \
  -H "Content-Type: application/json" \
  -d '{"query":"charade","limit":3}'
```

### n8n Webhook 常見問題

**Q: webhook-test 返回 404**
A: 需要在 n8n UI 中點擊 "Execute workflow" 按鈕後才能使用 test webhook

**Q: webhook (生產環境) 返回 404**
A: 需要將工作流程切換為 Active 狀態 (右上角開關)

---

## 附錄

### A. 服務 URL 列表

| 服務 | URL |
|------|-----|
| Momentry API (本地) | `http://localhost:3002` |
| Momentry API (外部) | `https://api.momentry.ddns.net` |
| n8n Web UI | `https://n8n.momentry.ddns.net` |
| n8n Webhook Test | `http://localhost:5678/webhook-test/{workflow-name}` |
| n8n Webhook Prod | `http://localhost:5678/webhook/{workflow-name}` |

### B. 所有可用端點

| 端點 | 方法 | 狀態 | 說明 |
|------|------|------|------|
| `/health` | GET | ✅ | 健康檢查 |
| `/health/detailed` | GET | ✅ | 詳細健康檢查 |
| `/api/v1/register` | POST | ✅ | 註冊影片 |
| `/api/v1/search` | POST | ✅ | 語意搜尋 |
| `/api/v1/n8n/search` | POST | ✅ | n8n 格式搜尋 |
| `/api/v1/search/hybrid` | POST | ✅ | 混合搜尋 |
| `/api/v1/lookup` | GET | ✅ | 查詢影片 |
| `/api/v1/videos` | GET | ✅ | 列出所有影片 |
| `/api/v1/progress/:uuid` | GET | ✅ | 處理進度 |
| `/api/v1/jobs` | GET | ✅ | 任務列表 |
| `/api/v1/jobs/:uuid` | GET | ✅ | 任務詳情 |
| `/api/v1/api-keys` | * | ⚠️ | API Key 管理 (規劃中) |

### C. 常見錯誤

| HTTP 狀態 | 說明 | 解決方式 |
|-----------|------|----------|
| 200 | 成功 | - |
| 400 | 請求格式錯誤 | 檢查 JSON 格式 |
| 404 | 端點不存在或資源未找到 | 確認端點 URL 正確 |
| 500 | 伺服器內部錯誤 | 檢查 API 服務日誌 |
| **502** | **Bad Gateway** | **API 服務未啟動，見下方說明** |

#### 502 Bad Gateway 錯誤

**問題**: 外部 URL `https://api.momentry.ddns.net` 返回 502

**原因**: Momentry Core API 服務未啟動

**解決方式**:

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

# 2. 如果未啟動，手動啟動
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist

# 3. 或使用本地測試（繞過反向代理）
curl http://localhost:3002/health

# 4. 檢查日誌
tail -50 /Users/accusys/momentry/log/momentry_api.error.log
```

### D. 範例腳本

```bash
#!/bin/bash
# api_test.sh - API 測試腳本

API_URL="http://localhost:3002"

# 健康檢查
echo "=== Health Check ==="
curl -s "$API_URL/health" | jq .

# 搜尋
echo -e "\n=== Search ==="
curl -s -X POST "$API_URL/api/v1/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"query": "test", "limit": 3}' | jq .

# 列出影片
echo -e "\n=== Videos ==="
curl -s -H "X-API-Key: YOUR_API_KEY" "$API_URL/api/v1/videos" | jq '.videos | length'
```

---

## 相關文件

- [API_INDEX.md](./API_INDEX.md) - 文件總覽（起點）
- [API_ENDPOINTS.md](./API_ENDPOINTS.md) - 端點完整說明
- [API_N8N_GUIDE.md](./API_N8N_GUIDE.md) - n8n 使用範例
- [API_WORDPRESS_GUIDE.md](./API_WORDPRESS_GUIDE.md) - WordPress 使用範例