momentry_core/docs/API_WORKFLOW_WORDPRESS_N8N.md

Momentry API 使用流程

目標: 從影片上傳到搜尋的完整流程
適用: WordPress / n8n 整合

---

流程總覽

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  1. 上傳    │ →  │  2. 註冊    │ →  │  3. 確認    │ →  │  4. 處理    │ →  │  5. 搜尋    │
│  SFTPGo     │    │  自動完成    │    │  UUID       │    │  查詢進度   │    │  測試       │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

---

Step 1: 上傳影片

方式 A: SFTP 上傳（推薦）

# 連線資訊
主機: momentry.ddns.net
連接埠: 2022
用戶名: demo
密碼: demopassword123

使用 FileZilla 或 SFTP 客戶端上傳到 / 目錄

方式 B: SFTP 命令列

sshpass -p "demopassword123" sftp -P 2022 demo@momentry.ddns.net

上傳後確認檔案在 SFTPGo 中的位置

---

Step 2: 自動註冊

上傳後，系統會自動：

1. 偵測新檔案
2. 計算 UUID（SHA256）
3. 建立資料庫記錄

無需手動操作

---

Step 3: 確認註冊成功

查詢所有影片

curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.momentry.ddns.net/api/v1/videos" | jq '.videos | length'

查詢特定檔案

curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.momentry.ddns.net/api/v1/videos" | jq '.videos[] | select(.file_name | contains("你的檔案名"))'

預期回應

{
  "uuid": "952f5854b9febad1",
  "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/你的檔案.mp4",
  "file_name": "你的檔案.mp4",
  "duration": 123.45,
  "width": 1920,
  "height": 1080
}

確認要點:

• ✅ UUID 已產生（16位 hex）
• ✅ file_path 正確
• ✅ duration > 0

---

Step 4: 查詢處理進度

取得任務 UUID

# 從影片資訊取得 job_id
curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.momentry.ddns.net/api/v1/videos" | \
  jq '.videos[] | select(.file_name == "你的檔案.mp4") | {uuid, job_id}'

查詢任務狀態

curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.momentry.ddns.net/api/v1/jobs/{uuid}"

任務狀態說明

status	說明	動作
pending	等待處理	等待中
processing	處理中	繼續輪詢
completed	已完成	可進入 Step 5
failed	處理失敗	檢查錯誤

n8n 輪詢範例

// n8n Workflow: 檢查處理狀態
const jobUuid = $input.item.json.job_uuid;

const response = await fetch(
  `https://api.momentry.ddns.net/api/v1/jobs/${jobUuid}`,
  {
    headers: {
      "X-API-Key": "YOUR_API_KEY"
    }
  }
);

const job = await response.json();

// 狀態檢查
if (job.status === 'completed') {
  return [{ json: { done: true, video_uuid: job.video_uuid } }];
} else {
  return [{ json: { done: false, status: job.status } }];
}

---

Step 5: 搜尋測試

處理完成後，資料會入庫到向量資料庫，可進行搜尋測試。

測試向量搜尋

curl -s -X POST "https://api.momentry.ddns.net/api/v1/search" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "測試關鍵字",
    "top_k": 5
  }'

---

完整 n8n Workflow 範例

┌──────────────┐
│  觸發 (定時)  │
└──────┬───────┘
       ▼
┌──────────────┐     ┌──────────────┐
│  查詢影片     │────►│  比對新檔案   │
│  /videos     │     │              │
└──────┬───────┘     └──────────────┘
       │                   │
       ▼                   ▼
┌──────────────┐     ┌──────────────┐
│  等待處理     │◄────│  輪詢任務狀態  │
│  /jobs/:uuid │     │  /jobs/:uuid │
└──────┬───────┘     └──────────────┘
       │
       ▼ (completed)
┌──────────────┐
│  搜尋測試     │
│  /search     │
└──────────────┘

---

快速參考

步驟	API	用途
查詢影片	GET /api/v1/videos	確認上傳成功
查詢任務	GET /api/v1/jobs/:uuid	查看處理進度
搜尋內容	POST /api/v1/search	測試搜尋功能

---

注意:

• 處理時間視影片長度而定（1分鐘影片約需 2-5 分鐘處理）
• 大量影片時建議分批上傳