Files

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

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

5.7 KiB

Raw Permalink Blame History

Momentry Core API 存取指南

項目	內容
版本	V1.3
日期	2026-03-25
用途	API 存取方式、端點與整合指南

版本歷史

版本	日期	目的	操作人	工具/模型
V1.3	2026-03-25	更新: n8n 搜尋回傳 `file_path` 取代 `media_url`，新增 API Key 驗證說明	OpenCode	deepseek-reasoner
V1.2	2026-03-24	更新網址與服務列表	Warren	OpenCode / MiniMax M2.5
V1.1	2026-03-23	初始版本	Warren	OpenCode / MiniMax M2.5

基本網址

環境	URL	說明
本地開發	`http://localhost:3002`	直接訪問 API，繞過反向代理
外部訪問	`https://api.momentry.ddns.net`	通過 Caddy 反向代理訪問，需網路可達

何時使用哪個 URL

使用 localhost:3002：

開發/測試環境
直接在伺服器上操作
當反向代理有問題時

使用 api.momentry.ddns.net：

n8n workflow 中呼叫 API
外部系統整合
生產環境

認證

所有 /api/v1/* 端點（除了健康檢查 /health 與 /health/detailed）都需要 API Key 認證。

請在請求標頭中加入：

X-API-Key: YOUR_API_KEY

目前示範使用的 API Key: demo_api_key_12345

注意: 正式環境請使用安全的 API Key 管理機制，避免在客戶端暴露 API Key。

影片搜尋 API

語意搜尋

端點： POST /api/v1/search

請求：

{
  "query": "charade",
  "limit": 5,
  "uuid": "a1b10138a6bbb0cd"
}

欄位	類型	必填	說明
`query`	字串	是	搜尋文字
`limit`	整數	否	最大回傳結果數（預設 10）
`uuid`	字串	否	依影片 UUID 過濾

回應：

{
  "results": [
    {
      "uuid": "a1b10138a6bbb0cd",
      "chunk_id": "sentence_0006",
      "chunk_type": "sentence",
      "start_time": 48.8,
      "end_time": 55.44,
      "text": "fun plot twists, Woody Dialog and charming performances...",
      "score": 0.526
    }
  ],
  "query": "charade"
}

n8n 整合搜尋

端點： POST /api/v1/n8n/search

請求：

{
  "query": "charade",
  "limit": 5
}

回應：

{
  "query": "charade",
  "count": 5,
  "hits": [
    {
      "id": "sentence_0006",
      "vid": "a1b10138a6bbb0cd",
      "start": 48.8,
      "end": 55.44,
      "title": "Chunk sentence_0006",
      "text": "fun plot twists...",
      "score": 0.526,
      "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/Old_Time_Movie_Show_-_Charade_1963.HD.mov"
    }
  ]
}

注意: API 現在返回 file_path（檔案系統路徑）而非 media_url（網頁 URL）。如需在網頁中播放影片，請將檔案路徑轉換為可訪問的 URL（例如透過 SFTPGo 分享連結）。

影片管理 API

列出所有影片

端點： GET /api/v1/videos

查詢影片資訊

端點： GET /api/v1/lookup?uuid={uuid} 或 GET /api/v1/lookup?path={path}

取得處理進度

端點： GET /api/v1/progress/{uuid}

區塊資料結構

每個搜尋結果包含影片播放的時間資訊：

欄位	說明
`uuid`	影片識別碼
`chunk_id`	區塊唯一識別碼
`chunk_type`	類型：`sentence`、`cut`、`time_based`
`start_time`	開始時間（秒）
`end_time`	結束時間（秒）
`text`	語音轉文字內容
`score`	相關性分數（0-1）

整合範例

JavaScript/fetch

const response = await fetch('http://localhost:3002/api/v1/search', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'  // 替換為實際的 API Key
  },
  body: JSON.stringify({ query: 'charade', limit: 5 })
});
const data = await response.json();
console.log(data.results);

PHP/cURL

$ch = curl_init('http://localhost:3002/api/v1/search');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'query' => 'charade',
  'limit' => 5
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Content-Type: application/json',
  'X-API-Key: YOUR_API_KEY'  // 替換為實際的 API Key
]);
$response = curl_exec($ch);
$data = json_decode($response, true);

影片嵌入網址

重要: API 現在返回 file_path（檔案系統路徑），而非直接可訪問的網址。您需要將檔案路徑轉換為 SFTPGo 分享連結才能嵌入影片。

檔案路徑轉換為網址：

API 返回的 file_path 範例：/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4
對應的 SFTPGo 分享連結：https://wp.momentry.ddns.net/demo/video.mp4
轉換方式：移除 /Users/accusys/momentry/var/sftpgo/data/ 前綴，將剩餘路徑附加到 https://wp.momentry.ddns.net/

手動建立分享連結：

開啟 SFTPGo Web UI：http://localhost:8080
使用帳號 demo / 密碼 demopassword123 登入
導航至 Files → 選擇影片檔案
點擊 Share → Create Link
複製產生的分享連結

使用搜尋結果中的 start_time 和 end_time 來嵌入影片片段。

服務列表

服務	網址	用途
Momentry API	`http://localhost:3002`	核心 API
SFTPGo	`http://localhost:8080`	檔案儲存
Qdrant	`http://localhost:6333`	向量搜尋
PostgreSQL	`localhost:5432`	資料庫

示範影片

檔案： Old_Time_Movie_Show_-_Charade_1963.HD.mov
UUID： a1b10138a6bbb0cd
長度： 約 6879 秒（約 1.9 小時）
區塊數： 3886 個（句子 + 場景 + 時間）

5.7 KiB Raw Permalink Blame History Unescape Escape