Files

Warren 82955504f3 feat: 新增 Job Worker 系統與 API 文檔全面更新

2026-03-26 16:16:34 +08:00

13 KiB

Raw Blame History

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: 部分功能需使用命令列工具

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

API 認證

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

-H "X-API-Key: YOUR_API_KEY"

目前示範使用的 API Key: demo_api_key_12345

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

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" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"path": "/path/to/video.mp4"}'

回應範例:

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

3.2 列出所有影片 ✅

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

3.3 查詢影片 ✅

# 依 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 命令：

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

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

3.5 取得處理進度 ✅

curl -H "X-API-Key: YOUR_API_KEY" 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"
    }
  ]
}

3.6 任務管理 ✅

# 列出所有任務
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>

任務列表回應範例:

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

任務詳情回應範例:

{
  "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 語意搜尋 ✅

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
  }'

回應範例:

{
  "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" \
  -H "X-API-Key: YOUR_API_KEY" \
  -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,
      "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"
    }
  ]
}

4.3 混合搜尋 ✅

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 健康檢查 ✅

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

解決方式:

# 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" \
  -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'

13 KiB Raw Blame History Unescape Escape

Momentry API 使用說明 (curl 範例)

版本歷史

目錄

URL 選擇指南

兩種 URL 的使用情境

何時使用 localhost:3002

何時使用 api.momentry.ddns.net

快速切換範例

常見問題

API 認證

1. 已實作端點

健康檢查

詳細健康檢查

2. API Key 管理 (規劃中)

2.1 建立 API Key

2.2 列出所有 API Keys

2.3 驗證 API Key

2.4 撤銷 API Key

2.5 請求 Key 輪換

2.6 取得統計資訊

3. 影片管理

3.1 註冊影片 ✅

3.2 列出所有影片 ✅

3.3 查詢影片 ✅

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

3.5 取得處理進度 ✅

3.6 任務管理 ✅

4. 查詢與搜索

4.1 語意搜尋 ✅

4.2 n8n 格式搜尋 ✅

4.3 混合搜尋 ✅

5. 系統狀態

5.1 健康檢查 ✅

5.2 詳細健康檢查 ✅

6. n8n Webhook 測試

測試 n8n Workflow

生產環境 Webhook

n8n Webhook 常見問題

附錄

A. 服務 URL 列表

B. 所有可用端點

C. 常見錯誤

502 Bad Gateway 錯誤

D. 範例腳本

相關文件

13 KiB

Raw Blame History