383201cacd
## v0.9.20260325_144654 ### Features - API Key Authentication System - Job Worker System - V2 Backup Versioning ### Bug Fixes - get_processor_results_by_job column mapping Co-authored-by: OpenCode
194 lines
4.1 KiB
Markdown
194 lines
4.1 KiB
Markdown
# 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`
|
||
|
||
**請求：**
|
||
```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,
|
||
"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
|
||
```javascript
|
||
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
|
||
```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']);
|
||
$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 個（句子 + 場景 + 時間）
|