231 lines
5.7 KiB
Markdown
231 lines
5.7 KiB
Markdown
# 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 個（句子 + 場景 + 時間）
|