# 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`

**請求：**
```json
{
  "query": "charade",
  "limit": 5,
  "uuid": "a1b10138a6bbb0cd"
}
```

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

**回應：**
```json
{
  "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`

**請求：**
```json
{
  "query": "charade",
  "limit": 5
}
```

**回應：**
```json
{
  "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
```javascript
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
```php
$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/`

**手動建立分享連結：**
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 個（句子 + 場景 + 時間）