momentry_core/docs/API_TRAINING_MARCOM.md

Momentry Core API 教育訓練手冊

對象: marcom 團隊
版本: V1.1 | 日期: 2026-03-25

---

1. 快速開始

基本資訊

項目	值
API 網址	https://api.momentry.ddns.net
認證方式	Header X-API-Key
格式	JSON

API Key

X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69

---

2. 快速範例

查詢所有影片

curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
  "https://api.momentry.ddns.net/api/v1/videos"

查詢單一影片

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

查詢處理任務狀態

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

---

3. API 端點說明

3.1 影片相關

GET /api/v1/videos

取得所有影片列表

回應範例:

{
  "videos": [
    {
      "uuid": "5dea6618a606e7c7",
      "filename": "demo_video.mp4",
      "duration": 123.45,
      "status": "ready",
      "created_at": "2026-03-25T10:00:00Z"
    }
  ]
}

GET /api/v1/videos/:uuid

取得單一影片詳情

3.2 搜尋與分段查詢

POST /api/v1/search

向量搜尋，查詢分段詳情

請求範例:

{
  "query": "關鍵字",
  "limit": 10
}

回應範例:

{
  "results": [
    {
      "uuid": "5dea6618a606e7c7",
      "chunk_id": "time_00001",
      "chunk_type": "time",
      "start_time": 0.0,
      "end_time": 10.0,
      "text": "分段內容文字",
      "score": 0.95
    }
  ]
}

POST /api/v1/n8n/search

n8n 專用搜尋（包含縮圖網址）

請求範例:

{
  "query": "關鍵字",
  "limit": 10
}

回應範例:

{
  "hits": [
    {
      "uuid": "5dea6618a606e7c7",
      "chunk_id": "time_00001",
      "chunk_type": "time",
      "start_time": 0.0,
      "end_time": 10.0,
      "text": "分段內容文字",
      "score": 0.95,
      "thumbnail_url": "https://..."
    }
  ]
}

3.3 任務相關

GET /api/v1/jobs/:uuid

查詢處理任務狀態

回應範例:

{
  "uuid": "9760d0820f0cf9a7",
  "video_uuid": "5dea6618a606e7c7",
  "status": "completed",
  "progress": 100,
  "created_at": "2026-03-25T10:00:00Z",
  "completed_at": "2026-03-25T10:05:00Z"
}

GET /api/v1/jobs

查詢所有任務

查詢參數:

參數	說明	範例
status	篩選狀態	pending, processing, completed, failed
limit	回傳數量	10

範例:

curl -s -H "X-API-Key: ..." \
  "https://api.momentry.ddns.net/api/v1/jobs?status=completed&limit=5"

3.3 系統管理

POST /api/v1/config/cache

切換快取功能（管理員專用）

請求範例:

{
  "enabled": true
}

回應範例:

{
  "cache_enabled": true,
  "message": "Cache toggled successfully"
}

POST /api/v1/unregister

刪除影片及其所有關聯資料（管理員專用）

請求範例:

{
  "uuid": "5dea6618a606e7c7"
}

回應範例:

{
  "success": true,
  "message": "Video unregistered successfully",
  "uuid": "5dea6618a606e7c7"
}

注意: 此操作會刪除影片及其所有分段、處理結果、縮圖等關聯資料，無法復原。

3.5 健康檢查

GET /health

服務健康狀態（無需認證）

回應:

{
  "status": "ok",
  "version": "0.9.20260325_144654"
}

---

4. n8n Workflow 範例

4.1 基本設定

在 n8n workflow 中使用 HTTP Request 節點：

┌─────────────────┐
│  HTTP Request   │
├─────────────────┤
│ Method: GET     │
│ URL: https://api.momentry.ddns.net/api/v1/videos
│ Headers:        │
│   X-API-Key:    │
│   [YOUR_KEY]    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  處理回應資料    │
└─────────────────┘

4.2 範例：檢查任務狀態

// n8n Function Node 範例
const jobUuid = $input.item.json.uuid;

return [{
  json: {
    method: "GET",
    url: `https://api.momentry.ddns.net/api/v1/jobs/${jobUuid}`,
    headers: {
      "X-API-Key": "YOUR_API_KEY"
    }
  }
}];

---

5. 常見問題

Q: 返回 401 錯誤怎麼辦？

確認 Header 中有正確的 X-API-Key 值

Q: 如何確認影片處理完成？

GET /api/v1/jobs/{uuid}

檢查 status 是否為 completed

Q: 查不到資料？

確認 UUID 格式正確（16碼 hex 字串）

---

6. 快速參考卡

┌─────────────────────────────────────────────────────────────┐
│                     Momentry API 速查                        │
├─────────────────────────────────────────────────────────────┤
│  查詢所有影片      GET  /api/v1/videos                       │
│  查詢單一影片      GET  /api/v1/videos/:uuid                │
│  向量搜尋          POST /api/v1/search                      │
│  n8n 搜尋          POST /api/v1/n8n/search                 │
│  查詢任務狀態      GET  /api/v1/jobs/:uuid                  │
│  查詢所有任務      GET  /api/v1/jobs                        │
│  快取設定          POST /api/v1/config/cache (管理員)       │
│  刪除影片          POST /api/v1/unregister (管理員)        │
│  健康檢查          GET  /health (免認證)                    │
├─────────────────────────────────────────────────────────────┤
│  Header: X-API-Key: [YOUR_KEY]                             │
│  URL: https://api.momentry.ddns.net                        │
└─────────────────────────────────────────────────────────────┘

---

附錄：回應狀態說明

任務狀態 (status)

狀態	說明
pending	等待處理
processing	處理中
completed	已完成
failed	處理失敗

影片狀態 (status)

狀態	說明
uploading	上傳中
pending	等待處理
processing	處理中
ready	已就緒
error	錯誤

---

附錄：版本歷史

版本	日期	內容	操作人
V1.0	2026-03-25	初版建立	OpenCode
V1.1	2026-03-25	新增快取/刪除 API、搜尋端點文件	OpenCode