warren/momentry_core
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
8f2208dd63f2283bae26d56524221f47ddb696a9
momentry_core/docs/API_TRAINING_MARCOM.md
Warren 59809dae1f chore: backup before migration to new repo
2026-04-23 16:46:02 +08:00

9.4 KiB
Raw Blame History

Momentry Core API 教育訓練手冊

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

1. 快速開始

基本資訊

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

Demo 測試帳號

API Key（用於 API 認證）

X-API-Key: muser_68600856036340bcafc01930eb4bd839

SFTPGo（用於影片上傳）

項目 值
SFTP 主機 sftpgo.momentry.ddns.net
SFTP 連接埠 2022
用戶名 demo
密碼 demopassword123
Web 管理介面 https://sftpgo.momentry.ddns.net

使用方式：透過 SFTP 上傳影片，系統會自動註冊並處理。

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

向量搜尋，查詢分段（Chunk）詳情

請求參數:

參數 類型 必填 說明
query string 是 搜尋關鍵字
limit number 否 回傳數量（預設 10）
uuid string 否 只搜尋指定影片

請求範例:

{
  "query": "天氣",
  "limit": 10,
  "uuid": "5dea6618a606e7c7"
}

回應範例:

{
  "results": [
    {
      "uuid": "39567a0eb16f39fd",
      "chunk_id": "sentence_1471",
      "chunk_type": "sentence",
      "start_time": 5309.08,
      "end_time": 5311.08,
      "text": "influenced by a vital way,",
      "score": 0.68
    }
  ],
  "query": "天氣"
}

Chunk 欄位說明:

欄位 說明 範例
uuid 影片唯一識別碼 39567a0eb16f39fd
chunk_id 分段識別碼 sentence_1471
chunk_type 分段類型 sentence / cut / time / trace / story
start_time 開始時間（秒） 5309.08
end_time 結束時間（秒） 5311.08
text 內容文字 influenced by a vital way
score 相似度分數（0-1） 0.68

Chunk 類型說明:

類型 說明 來源
sentence 語音轉文字片段 ASR 處理
cut 場景變化片段 CUT 處理
time 固定時間分段 系統自動切割
trace 軌跡追蹤片段 YOLO 追蹤
story 故事線片段（父子關係） Story 分析

POST /api/v1/n8n/search

n8n 專用搜尋（包含完整影片檔案路徑 file_path）

請求參數: 與 /search 相同

回應範例:

{
  "query": "天氣",
  "count": 2,
  "hits": [
    {
      "id": "sentence_1471",
      "vid": "39567a0eb16f39fd",
      "chunk_type": "sentence",
      "start_frame": 318545,
      "end_frame": 318665,
      "fps": 59.94,
      "start_time": 5314.31,
      "end_time": 5316.32,
      "text": "influenced by a vital way,",
      "score": 0.68
    }
  ]
}

與 /search 的差異:

欄位 /search /n8n/search
影片 UUID uuid vid
Chunk ID chunk_id id
開始時間 start_time start_time
結束時間 end_time end_time
相似度分數 score score
檔案路徑 ❌ ✅ file_path

注意: file_path 是影片的實際路徑，可用於本地播放。

3.3 任務相關

3.4 任務相關

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.5 系統管理

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

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
V1.2 2026-03-25 新增 Chunk 欄位說明、類型、播放方式 OpenCode
V1.3 2026-03-25 新增 Demo 測試帳號（SFTPGo） OpenCode
V1.4 2026-03-25 更新 n8n 搜尋回傳欄位說明 (media_url→file_path) OpenCode
V1.5 2026-04-17 修正 API Key 格式、統一 n8n/search 欄位名稱 (start/end → start_time/end_time) OpenCode
Reference in New Issue View Git Blame Copy Permalink