# 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 個（句子 + 場景 + 時間）