momentry_core/docs/API_ACCESS.md

Momentry Core API 存取指南

基本網址

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

何時使用哪個 URL

使用 localhost:3002：

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

使用 api.momentry.ddns.net：

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

認證

目前為開放狀態（示範用途無需認證）。正式環境將實作 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,
      "media_url": "https://wp.momentry.ddns.net/Old_Time_Movie_Show_-_Charade_1963.HD.mov"
    }
  ]
}

---

影片管理 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' },
  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']);
$response = curl_exec($ch);
$data = json_decode($response, true);

---

影片嵌入網址

影片可透過 SFTPGo 分享連結存取：

https://wp.momentry.ddns.net/{檔案名稱}

手動建立分享連結：

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

使用搜尋結果中的 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 個（句子 + 場景 + 時間）