# Momentry Core API 教育訓練手冊

> **對象**: marcom 團隊  
> **版本**: V1.2 | **日期**: 2026-03-25

---

## 1. 快速開始

### 基本資訊

| 項目 | 值 |
|------|-----|
| API 網址 | `https://api.momentry.ddns.net` |
| 認證方式 | Header `X-API-Key` |
| 格式 | JSON |

### Demo 測試帳號

#### API Key（用於 API 認證）

```
X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69
```

#### SFTPGo（用於影片上傳）

| 項目 | 值 |
|------|-----|
| SFTP 主機 | `sftpgo.momentry.ddns.net` |
| SFTP 連接埠 | `2022` |
| 用戶名 | `demo` |
| 密碼 | `demopassword123` |
| Web 管理介面 | `https://sftpgo.momentry.ddns.net` |

**使用方式**：透過 SFTP 上傳影片，系統會自動註冊並處理。

---

## 2. 快速範例

### 查詢所有影片

```bash
curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
  "https://api.momentry.ddns.net/api/v1/videos"
```

### 查詢單一影片

```bash
curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
  "https://api.momentry.ddns.net/api/v1/videos/{uuid}"
```

### 查詢處理任務狀態

```bash
curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
  "https://api.momentry.ddns.net/api/v1/jobs/{uuid}"
```

---

## 3. API 端點說明

### 3.1 影片相關

#### GET /api/v1/videos
取得所有影片列表

**回應範例**:
```json
{
  "videos": [
    {
      "uuid": "5dea6618a606e7c7",
      "filename": "demo_video.mp4",
      "duration": 123.45,
      "status": "ready",
      "created_at": "2026-03-25T10:00:00Z"
    }
  ]
}
```

#### GET /api/v1/videos/:uuid
取得單一影片詳情

### 3.2 搜尋與分段查詢

#### POST /api/v1/search
向量搜尋，查詢分段（Chunk）詳情

**請求參數**:
| 參數 | 類型 | 必填 | 說明 |
|------|------|------|------|
| `query` | string | 是 | 搜尋關鍵字 |
| `limit` | number | 否 | 回傳數量（預設 10） |
| `uuid` | string | 否 | 只搜尋指定影片 |

**請求範例**:
```json
{
  "query": "天氣",
  "limit": 10,
  "uuid": "5dea6618a606e7c7"
}
```

**回應範例**:
```json
{
  "results": [
    {
      "uuid": "39567a0eb16f39fd",
      "chunk_id": "sentence_1471",
      "chunk_type": "sentence",
      "start_time": 5309.08,
      "end_time": 5311.08,
      "text": "influenced by a vital way,",
      "score": 0.68
    }
  ],
  "query": "天氣"
}
```

**Chunk 欄位說明**:
| 欄位 | 說明 | 範例 |
|------|------|------|
| `uuid` | 影片唯一識別碼 | `39567a0eb16f39fd` |
| `chunk_id` | 分段識別碼 | `sentence_1471` |
| `chunk_type` | 分段類型 | `sentence` / `cut` / `time` / `trace` / `story` |
| `start_time` | 開始時間（秒） | `5309.08` |
| `end_time` | 結束時間（秒） | `5311.08` |
| `text` | 內容文字 | `influenced by a vital way` |
| `score` | 相似度分數（0-1） | `0.68` |

**Chunk 類型說明**:
| 類型 | 說明 | 來源 |
|------|------|------|
| `sentence` | 語音轉文字片段 | ASR 處理 |
| `cut` | 場景變化片段 | CUT 處理 |
| `time` | 固定時間分段 | 系統自動切割 |
| `trace` | 軌跡追蹤片段 | YOLO 追蹤 |
| `story` | 故事線片段（父子關係） | Story 分析 |

#### POST /api/v1/n8n/search
n8n 專用搜尋（包含完整影片網址 media_url）

**請求參數**: 與 `/search` 相同

**回應範例**:
```json
{
  "query": "天氣",
  "count": 2,
  "hits": [
    {
      "id": "sentence_1471",
      "vid": "39567a0eb16f39fd",
      "start": 5309.08,
      "end": 5311.08,
      "title": "Chunk sentence_1471",
      "text": "influenced by a vital way,",
      "score": 0.68,
      "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"
    }
  ]
}
```

**與 /search 的差異**:
| 欄位 | `/search` | `/n8n/search` |
|------|-----------|----------------|
| 影片 UUID | `uuid` | `vid` |
| Chunk ID | `chunk_id` | `id` |
| 開始時間 | `start_time` | `start` |
| 結束時間 | `end_time` | `end` |
| 相似度分數 | `score` | `score` |
| **檔案路徑** | ❌ | ✅ `file_path` |

> **注意**: `file_path` 是影片的實際路徑，可用於本地播放。

### 3.3 任務相關

### 3.4 任務相關

#### GET /api/v1/jobs/:uuid
查詢處理任務狀態

**回應範例**:
```json
{
  "uuid": "9760d0820f0cf9a7",
  "video_uuid": "5dea6618a606e7c7",
  "status": "completed",
  "progress": 100,
  "created_at": "2026-03-25T10:00:00Z",
  "completed_at": "2026-03-25T10:05:00Z"
}
```

#### GET /api/v1/jobs
查詢所有任務

**查詢參數**:
| 參數 | 說明 | 範例 |
|------|------|------|
| `status` | 篩選狀態 | `pending`, `processing`, `completed`, `failed` |
| `limit` | 回傳數量 | `10` |

**範例**:
```bash
curl -s -H "X-API-Key: ..." \
  "https://api.momentry.ddns.net/api/v1/jobs?status=completed&limit=5"
```

### 3.5 系統管理

#### POST /api/v1/config/cache
切換快取功能（管理員專用）

**請求範例**:
```json
{
  "enabled": true
}
```

**回應範例**:
```json
{
  "cache_enabled": true,
  "message": "Cache toggled successfully"
}
```

#### POST /api/v1/unregister
刪除影片及其所有關聯資料（管理員專用）

**請求範例**:
```json
{
  "uuid": "5dea6618a606e7c7"
}
```

**回應範例**:
```json
{
  "success": true,
  "message": "Video unregistered successfully",
  "uuid": "5dea6618a606e7c7"
}
```

**注意**: 此操作會刪除影片及其所有分段、處理結果、縮圖等關聯資料，**無法復原**。

### 3.6 健康檢查

#### GET /health
服務健康狀態（**無需認證**）

**回應**:
```json
{
  "status": "ok",
  "version": "0.9.20260325_144654"
}
```

---

## 4. n8n Workflow 範例

### 4.1 基本設定

在 n8n workflow 中使用 HTTP Request 節點：

```
┌─────────────────┐
│  HTTP Request   │
├─────────────────┤
│ Method: GET     │
│ URL: https://api.momentry.ddns.net/api/v1/videos
│ Headers:        │
│   X-API-Key:    │
│   [YOUR_KEY]    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  處理回應資料    │
└─────────────────┘
```

### 4.2 範例：檢查任務狀態

```javascript
// n8n Function Node 範例
const jobUuid = $input.item.json.uuid;

return [{
  json: {
    method: "GET",
    url: `https://api.momentry.ddns.net/api/v1/jobs/${jobUuid}`,
    headers: {
      "X-API-Key": "YOUR_API_KEY"
    }
  }
}];
```

---

## 5. 常見問題

### Q: 返回 401 錯誤怎麼辦？
確認 Header 中有正確的 `X-API-Key` 值

### Q: 如何確認影片處理完成？
```
GET /api/v1/jobs/{uuid}
```
檢查 `status` 是否為 `completed`

### Q: 查不到資料？
確認 UUID 格式正確（16碼 hex 字串）

---

## 6. 快速參考卡

```
┌─────────────────────────────────────────────────────────────┐
│                     Momentry API 速查                        │
├─────────────────────────────────────────────────────────────┤
│  查詢所有影片      GET  /api/v1/videos                       │
│  查詢單一影片      GET  /api/v1/videos/:uuid                │
│  向量搜尋          POST /api/v1/search                      │
│  n8n 搜尋          POST /api/v1/n8n/search                 │
│  查詢任務狀態      GET  /api/v1/jobs/:uuid                  │
│  查詢所有任務      GET  /api/v1/jobs                        │
│  快取設定          POST /api/v1/config/cache (管理員)       │
│  刪除影片          POST /api/v1/unregister (管理員)        │
│  健康檢查          GET  /health (免認證)                    │
├─────────────────────────────────────────────────────────────┤
│  Header: X-API-Key: [YOUR_KEY]                             │
│  URL: https://api.momentry.ddns.net                        │
└─────────────────────────────────────────────────────────────┘
```

---

## 附錄：回應狀態說明

### 任務狀態 (status)

| 狀態 | 說明 |
|------|------|
| `pending` | 等待處理 |
| `processing` | 處理中 |
| `completed` | 已完成 |
| `failed` | 處理失敗 |

### 影片狀態 (status)

| 狀態 | 說明 |
|------|------|
| `uploading` | 上傳中 |
| `pending` | 等待處理 |
| `processing` | 處理中 |
| `ready` | 已就緒 |
| `error` | 錯誤 |

---

## 附錄：版本歷史

| 版本 | 日期 | 內容 | 操作人 |
|------|------|------|--------|
| V1.0 | 2026-03-25 | 初版建立 | OpenCode |
| V1.1 | 2026-03-25 | 新增快取/刪除 API、搜尋端點文件 | OpenCode |
| V1.2 | 2026-03-25 | 新增 Chunk 欄位說明、類型、播放方式 | OpenCode |
| V1.3 | 2026-03-25 | 新增 Demo 測試帳號（SFTPGo）| OpenCode |