momentry_core/docs/API_CURL_EXAMPLES.md

Momentry API 使用說明 (curl 範例)

項目	內容
版本	V1.2
日期	2026-03-23
Base URL	http://localhost:3002

---

狀態說明:

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

---

目錄

1. 已實作端點
2. API Key 管理
3. 影片管理
4. 查詢與搜索
5. 系統狀態

---

URL 選擇指南

兩種 URL 的使用情境

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

何時使用 localhost:3002

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

何時使用 api.momentry.ddns.net

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

快速切換範例

# 本地測試
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 服務是否運行：

launchctl list | grep momentry.api
# 如果未運行
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist

---

1. 已實作端點

健康檢查

curl http://localhost:3002/health

回應:

{"status":"ok","version":"0.1.0","uptime_ms":123456}

詳細健康檢查

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

---

2. API Key 管理 (規劃中)

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

2.1 建立 API Key

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

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

2.3 驗證 API Key

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

2.4 撤銷 API Key

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

2.5 請求 Key 輪換

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 取得統計資訊

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

---

3. 影片管理

3.1 註冊影片 ✅

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

回應範例:

{
  "id": 1,
  "uuid": "a1b2c3d4e5f6g7h8",
  "file_path": "/path/to/video.mp4",
  "file_name": "video.mp4",
  "duration": 120.5,
  "width": 1920,
  "height": 1080
}

3.2 列出所有影片 ✅

curl http://localhost:3002/api/v1/videos

3.3 查詢影片 ✅

# 依 UUID 查詢
curl "http://localhost:3002/api/v1/lookup?uuid=a1b2c3d4e5f6g7h8"

# 依路徑查詢
curl "http://localhost:3002/api/v1/lookup?path=/path/to/video.mp4"

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

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

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

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

3.5 取得處理進度 ✅

curl http://localhost:3002/api/v1/progress/<uuid>

回應範例:

{
  "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"
    }
  ]
}

---

4. 查詢與搜索

4.1 語意搜尋 ✅

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

回應範例:

{
  "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 格式搜尋 ✅

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

回應範例:

{
  "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,
      "media_url": "https://wp.momentry.ddns.net/video.mp4"
    }
  ]
}

4.3 混合搜尋 ✅

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

---

5. 系統狀態

5.1 健康檢查 ✅

curl http://localhost:3002/health

回應:

{"status":"ok","version":"0.1.0","uptime_ms":123456}

5.2 詳細健康檢查 ✅

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

回應範例:

{
  "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" 按鈕

# 測試 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 狀態

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/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 服務未啟動

解決方式:

# 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. 範例腳本

#!/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" \
  -d '{"query": "test", "limit": 3}' | jq .

# 列出影片
echo -e "\n=== Videos ==="
curl -s "$API_URL/api/v1/videos" | jq '.videos | length'

---

相關文件

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