# Momentry Core API 教育訓練手冊

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

---

## 1. 快速開始

### 基本資訊

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

### API Key

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

---

## 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 任務相關

#### 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.3 系統管理

#### 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.4 健康檢查

#### 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                │
│  查詢任務狀態      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.1  
**最後更新**: 2026-03-25