Files

Warren 1f84e5469f feat: backup architecture docs, source code, and scripts

2026-04-25 17:15:45 +08:00

6.8 KiB

Raw Permalink Blame History

Momentry Core API 端點總覽

項目	內容
建立者	Warren
建立時間	2026-03-18
文件版本	V1.3

版本歷史

版本	日期	目的	操作人
V1.0	2026-03-18	創建文件	OpenCode
V1.1	2026-03-23	更新端點與實際一致	OpenCode
V1.2	2026-03-25	新增快取/刪除 API	OpenCode
V1.3	2026-03-26	更新API回應格式 (media_url→file_path)	OpenCode

Base URL

環境	URL
本地	`http://localhost:3002`
外部	`https://api.momentry.ddns.net`

認證

除健康檢查端點外，所有 API 端點都需要 API Key。

Header 方式

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

響應

401 Unauthorized - 缺少或無效的 API Key
200 OK - 認證成功

取得 API Key

使用 CLI 建立：

./target/release/momentry api-key create "My API Key" --key-type user

端點列表

健康檢查（公開）

方法	端點	說明
GET	`/health`	基本健康檢查
GET	`/health/detailed`	詳細健康檢查（含服務狀態）

範例:

curl http://localhost:3002/health
# {"status":"ok","version":"0.1.0","uptime_ms":123456}

影片搜尋

方法	端點	說明
POST	`/api/v1/search`	語意搜尋（標準格式）
POST	`/api/v1/n8n/search`	語意搜尋（n8n 專用格式）
POST	`/api/v1/search/hybrid`	混合搜尋

標準搜尋 (/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": "test", "limit": 10}'

n8n 格式搜尋 (/api/v1/n8n/search):

curl -X POST http://localhost:3002/api/v1/n8n/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"query": "test", "limit": 10}'

影片管理

方法	端點	說明
POST	`/api/v1/register`	註冊影片
POST	`/api/v1/probe`	探測影片資訊（不註冊）
GET	`/api/v1/videos`	列出所有影片
GET	`/api/v1/lookup`	查詢影片資訊
GET	`/api/v1/progress/:uuid`	取得處理進度

註冊影片:

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": "a1b10138a6bbb0cd",
  "video_id": 1,
  "job_id": 10,
  "file_name": "video.mp4",
  "duration": 120.5,
  "width": 1920,
  "height": 1080,
  "already_exists": false
}

探測影片 (不註冊，只取得影片資訊):

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

Probe 回應範例:

{
  "uuid": "a1b10138a6bbb0cd",
  "file_name": "video.mp4",
  "duration": 120.5,
  "width": 1920,
  "height": 1080,
  "fps": 30.0,
  "cached": false,
  "format": {
    "filename": "/path/to/video.mp4",
    "format_name": "mov,mp4,m4a,3gp,3g2,mj2",
    "duration": "120.5",
    "size": "12345678",
    "bit_rate": "819200"
  },
  "streams": [
    {
      "index": 0,
      "codec_name": "h264",
      "codec_type": "video",
      "width": 1920,
      "height": 1080,
      "r_frame_rate": "30/1",
      "duration": "120.5"
    }
  ]
}

列出影片:

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

查詢影片:

curl -H "X-API-Key: your-api-key" "http://localhost:3002/api/v1/lookup?uuid=5dea6618a606e7c7"

處理進度:

curl -H "X-API-Key: your-api-key" http://localhost:3002/api/v1/progress/5dea6618a606e7c7

工作管理

方法	端點	說明
GET	`/api/v1/jobs`	列出所有工作
GET	`/api/v1/jobs/:uuid`	取得指定工作的詳細資訊

列出工作:

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/a03485a40b2df2d3

系統管理

方法	端點	說明
POST	`/api/v1/config/cache`	切換快取功能（管理員）
POST	`/api/v1/unregister`	刪除影片及其所有資料（管理員）

快取設定:

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

刪除影片:

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

端點對照表

功能	n8n 使用	WordPress 使用	curl 測試
健康檢查	✓	✓	✓
語意搜尋	✓ (n8n格式)	✓ (標準格式)	✓
影片探測	✓	✓	✓
註冊影片	✓	✓	✓
列出影片	✓	✓	✓
查詢影片	✓	✓	✓
處理進度	✓	✓	✓
工作管理	✓	✓	✓
快取設定	✓ (管理員)	✓ (管理員)	✓ (管理員)
刪除影片	✓ (管理員)	✓ (管理員)	✓ (管理員)

回應格式

n8n 格式 (`/api/v1/n8n/search`)

{
  "query": "charade",
  "count": 10,
  "hits": [
    {
      "id": "sentence_0001",
      "vid": "a1b10138a6bbb0cd",
      "start": 48.8,
      "end": 55.44,
      "title": "Chunk sentence_0001",
      "text": "...",
      "score": 0.92,
      "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"
    }
  ]
}

標準格式 (`/api/v1/search`)

{
  "results": [
    {
      "uuid": "a1b10138a6bbb0cd",
      "chunk_id": "sentence_0001",
      "chunk_type": "sentence",
      "start_time": 48.8,
      "end_time": 55.44,
      "text": "...",
      "score": 0.92
    }
  ],
  "query": "charade"
}

HTTP 狀態碼

狀態	說明
200	成功
400	請求格式錯誤
404	端點或資源不存在
500	伺服器內部錯誤
502	API 服務未啟動

錯誤處理

502 Bad Gateway

原因: Momentry API 服務未啟動

解決:

sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist

6.8 KiB Raw Permalink Blame History Unescape Escape