Files

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

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

11 KiB

Raw Blame History

Momentry Core API 快速查詢表

版本	日期	建立者
V1.0	2026-03-26	OpenCode

📋 快速導覽

類別	端點數量	說明
健康檢查	2	系統狀態監控
影片管理	5	影片註冊、查詢、刪除
搜尋功能	3	語意搜尋、混合搜尋
任務管理	2	處理任務狀態查詢
系統管理	2	快取設定、進度查詢

🔐 認證

所有 /api/v1/* 端點需要 X-API-Key header：

curl -H "X-API-Key: YOUR_API_KEY" ...

公開端點（無需認證）：

GET /health
GET /health/detailed

📊 端點總表

健康檢查

方法	端點	認證	描述
GET	`/health`	公開	基本健康檢查
GET	`/health/detailed`	公開	詳細健康檢查（包含所有服務狀態）

影片管理

方法	端點	認證	描述
POST	`/api/v1/register`	需要	註冊影片並開始處理
POST	`/api/v1/unregister`	需要	刪除影片及其所有資料
POST	`/api/v1/probe`	需要	探測影片資訊（不註冊）
GET	`/api/v1/videos`	需要	列出所有已註冊影片
GET	`/api/v1/lookup`	需要	查詢影片資訊

搜尋功能

方法	端點	認證	描述
POST	`/api/v1/search`	需要	語意搜尋（標準格式）
POST	`/api/v1/n8n/search`	需要	語意搜尋（n8n 格式）
POST	`/api/v1/search/hybrid`	需要	混合搜尋（向量 + 關鍵字）

任務管理

方法	端點	認證	描述
GET	`/api/v1/jobs`	需要	列出所有處理任務
GET	`/api/v1/jobs/:uuid`	需要	取得特定任務詳情

系統管理

方法	端點	認證	描述
GET	`/api/v1/progress/:uuid`	需要	取得影片處理進度
POST	`/api/v1/config/cache`	需要	切換快取功能

🔧 詳細端點說明

1. 健康檢查

GET /health

基本健康檢查

curl http://localhost:3002/health

回應：

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

GET /health/detailed

詳細健康檢查

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

回應：

{
  "status": "ok",
  "version": "0.1.0",
  "uptime_ms": 14441362,
  "services": {
    "postgres": {"status": "ok", "latency_ms": 50, "error": null},
    "redis": {"status": "ok", "latency_ms": 0, "error": null},
    "qdrant": {"status": "ok", "latency_ms": 2, "error": null},
    "mongodb": {"status": "ok", "latency_ms": 2, "error": null}
  }
}

2. 影片管理

POST /api/v1/register

註冊影片並開始處理

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

請求：

{
  "path": "/path/to/video.mp4"
}

回應：

{
  "uuid": "5dea6618a606e7c7",
  "video_id": 10,
  "job_id": 1,
  "file_name": "video.mp4",
  "duration": 596.458333,
  "width": 320,
  "height": 180,
  "already_exists": false
}

POST /api/v1/unregister

刪除影片及其所有資料

curl -X POST http://localhost:3002/api/v1/unregister \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"uuid": "5dea6618a606e7c7"}'

請求：

{
  "uuid": "5dea6618a606e7c7"
}

回應：

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

POST /api/v1/probe

探測影片資訊（不註冊）

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

請求：

{
  "path": "/path/to/video.mp4"
}

回應：

{
  "uuid": "5dea6618a606e7c7",
  "file_name": "video.mp4",
  "duration": 596.458333,
  "width": 320,
  "height": 180,
  "fps": 24.0,
  "cached": true,
  "format": {...},
  "streams": [...]
}

GET /api/v1/videos

列出所有已註冊影片

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

回應：

{
  "videos": [
    {
      "uuid": "a03485a40b2df2d3",
      "file_path": "/path/to/video.mp4",
      "file_name": "video.mp4",
      "duration": 596.458333,
      "width": 320,
      "height": 180
    }
  ]
}

GET /api/v1/lookup

查詢影片資訊

# 依 UUID 查詢
curl -H "X-API-Key: YOUR_API_KEY" "http://localhost:3002/api/v1/lookup?uuid=a03485a40b2df2d3"

# 依路徑查詢
curl -H "X-API-Key: YOUR_API_KEY" "http://localhost:3002/api/v1/lookup?path=/path/to/video.mp4"

回應：

{
  "uuid": "a03485a40b2df2d3",
  "file_path": "/path/to/video.mp4",
  "file_name": "video.mp4",
  "duration": 596.458333
}

3. 搜尋功能

POST /api/v1/search

語意搜尋（標準格式）

curl -X POST http://localhost:3002/api/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"query": "search term", "limit": 5}'

請求：

{
  "query": "search term",
  "limit": 5
}

回應：

{
  "results": [
    {
      "uuid": "a1b10138a6bbb0cd",
      "chunk_id": "sentence_0001",
      "chunk_type": "sentence",
      "start_time": 10.5,
      "end_time": 15.2,
      "text": "Found text matching query",
      "score": 0.85
    }
  ],
  "query": "search term"
}

POST /api/v1/n8n/search

語意搜尋（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": "search term", "limit": 5}'

回應：

{
  "query": "search term",
  "count": 1,
  "hits": [
    {
      "id": "sentence_0001",
      "vid": "a1b10138a6bbb0cd",
      "start": 10.5,
      "end": 15.2,
      "title": "Chunk sentence_0001",
      "text": "Found text matching query",
      "score": 0.85,
      "file_path": "/path/to/video.mp4"
    }
  ]
}

POST /api/v1/search/hybrid

混合搜尋（向量 + 關鍵字）

curl -X POST http://localhost:3002/api/v1/search/hybrid \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"query": "search term", "limit": 5}'

請求：

{
  "query": "search term",
  "limit": 5
}

回應： 與 /api/v1/search 相同格式

4. 任務管理

GET /api/v1/jobs

列出所有處理任務

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

回應：

{
  "jobs": [
    {
      "id": 10,
      "uuid": "a03485a40b2df2d3",
      "status": "running",
      "current_processor": null,
      "progress_current": 0,
      "progress_total": 0,
      "created_at": "2026-03-26 13:39:37.830465",
      "started_at": null
    }
  ]
}

GET /api/v1/jobs/:uuid

取得特定任務詳情

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

回應：

{
  "id": 10,
  "uuid": "a03485a40b2df2d3",
  "status": "running",
  "current_processor": null,
  "progress_current": 0,
  "progress_total": 0,
  "processors": [
    {
      "processor_type": "asr",
      "status": "completed",
      "started_at": "2026-03-26 05:39:40.275468",
      "completed_at": "2026-03-26 07:19:43.166613",
      "duration_secs": 6002.891145,
      "error_message": null
    },
    // ... 其他處理器
  ],
  "created_at": "2026-03-26 13:39:37.830465",
  "started_at": null,
  "updated_at": "2026-03-26 07:19:16.338406"
}

5. 系統管理

GET /api/v1/progress/:uuid

取得影片處理進度

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

回應：

{
  "uuid": "a03485a40b2df2d3",
  "user": null,
  "group": null,
  "file_name": "video.mp4",
  "duration": 596.458333,
  "overall_progress": 0,
  "cpu_percent": 0.2,
  "gpu_percent": null,
  "memory_percent": 0.1,
  "memory_mb": 16720,
  "processors": [
    {
      "name": "asr",
      "status": "pending",
      "current": 0,
      "total": 0,
      "progress": 0,
      "message": ""
    },
    // ... 其他處理器
  ]
}

POST /api/v1/config/cache

切換快取功能

curl -X POST http://localhost:3002/api/v1/config/cache \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"enabled": true}'

請求：

{
  "enabled": true
}

回應：

{
  "success": true,
  "cache_enabled": true,
  "message": "Cache enabled"
}

🚀 快速工作流程

1. 註冊並處理影片

# 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: 5dea6618a606e7c7

# 2. 監控進度
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/progress/5dea6618a606e7c7

# 3. 查看任務狀態
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/jobs/5dea6618a606e7c7

2. 搜尋影片內容

# 1. 列出所有影片
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:3002/api/v1/videos

# 2. 搜尋內容
curl -X POST http://localhost:3002/api/v1/n8n/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"query": "charade scene", "limit": 10}'

3. 系統管理

# 1. 檢查系統健康
curl http://localhost:3002/health/detailed

# 2. 管理快取
curl -X POST http://localhost:3002/api/v1/config/cache \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"enabled": false}'

# 3. 刪除影片（需要時）
curl -X POST http://localhost:3002/api/v1/unregister \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"uuid": "5dea6618a606e7c7"}'

📝 注意事項

API Key 格式：
- 使用完整 API Key：muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69
- 系統存儲的是 SHA256 哈希值
路徑格式：
- 絕對路徑：/Users/accusys/test_video/video.mp4
- 相對路徑：./demo/video.mp4（相對於 SFTPGo 資料目錄）
回應時間：
- 健康檢查：< 100ms
- 搜尋：取決於查詢複雜度，通常 100-500ms
- 影片註冊：立即返回，背景處理可能需要數分鐘到數小時
錯誤處理：
- 401: 認證失敗
- 404: 資源不存在
- 500: 伺服器內部錯誤

🔗 相關文件

API 參考指南 - 詳細 API 說明
API 範例總覽 - 完整使用範例
API 端點列表 - 端點簡介
Curl 範例指南 - curl 命令範例
n8n 整合指南 - n8n 工作流程整合

11 KiB Raw Blame History Unescape Escape

Momentry Core API 快速查詢表

📋 快速導覽

🔐 認證

📊 端點總表

健康檢查

影片管理

搜尋功能

任務管理

系統管理

🔧 詳細端點說明

1. 健康檢查

GET /health

GET /health/detailed

2. 影片管理

POST /api/v1/register

POST /api/v1/unregister

POST /api/v1/probe

GET /api/v1/videos

GET /api/v1/lookup

3. 搜尋功能

POST /api/v1/search

POST /api/v1/n8n/search

POST /api/v1/search/hybrid

4. 任務管理

GET /api/v1/jobs

GET /api/v1/jobs/:uuid

5. 系統管理

GET /api/v1/progress/:uuid

POST /api/v1/config/cache

🚀 快速工作流程

1. 註冊並處理影片

2. 搜尋影片內容

3. 系統管理

📝 注意事項

🔗 相關文件

11 KiB

Raw Blame History