# Momentry API 教材 — Marcom 團隊必備

**版本**：v1.0  
**適用**：Marcom 團隊日常使用  
**難度**：初階，附 curl 指令範例  

---

## 目錄

1. [什麼是 Momentry API？](#1-什麼是-momentry-api)
2. [環境準備](#2-環境準備)
3. [API Key 認證](#3-api-key-認證)
4. [常用功能 ①：註冊影片](#4-常用功能-①註冊影片)
5. [常用功能 ②：查詢影片列表](#5-常用功能-②查詢影片列表)
6. [常用功能 ③：查詢影片詳細資料](#6-常用功能-③查詢影片詳細資料)
7. [常用功能 ④：搜尋對話內容](#7-常用功能-④搜尋對話內容)
8. [常用功能 ⑤：搜尋人物](#8-常用功能-⑤搜尋人物)
9. [常用功能 ⑥：觀看影片](#9-常用功能-⑥觀看影片)
10. [常用功能 ⑦：取得影片截圖](#10-常用功能-⑦取得影片截圖)
11. [進階功能：觸發影片處理](#11-進階功能觸發影片處理)
12. [進階功能：查詢處理進度](#12-進階功能查詢處理進度)
13. [常見問題](#13-常見問題)

---

## 1. 什麼是 Momentry API？

Momentry API 是一個 HTTP-based 的影片分析服務。你上傳一支影片，系統會自動：

- 🎬 **偵測場景變化** — 找出影片中每一幕的切換點
- 🗣️ **語音轉文字 (ASR)** — 把對話轉成可搜尋的文字
- 👤 **人臉辨識** — 辨識影片中出現的人物
- 🔍 **全文搜尋** — 用關鍵字搜尋對話內容

### 基本概念

| 名詞 | 說明 | 舉例 |
|------|------|------|
| **file_uuid** | 每支影片的唯一識別碼 | `aeed71342a899fe4b4c57b7d41bcb692` |
| **chunk** | 影片中的一段（對話、場景） | `"Hello and welcome..."` |
| **trace_id** | 同一個人臉的追蹤編號 | `trace_0`, `trace_1` |
| **identity** | 人物身份 | Cary Grant, Audrey Hepburn |
| **API Key** | 存取 API 的鑰匙 | `muser_test_apikey` |

---

## 2. 環境準備

### 2.1 工具

只需要一個工具：**curl**（命令列 HTTP 客戶端）。

macOS / Linux 內建，打開終端機即可使用：

```bash
curl --version
```

### 2.2 API 連線資訊

| 環境 | API 位址 | 用途 |
|------|---------|------|
| **開發環境 (dev)** | `http://192.168.110.210:3003` | 測試用 |
| **正式環境 (production)** | `http://192.168.110.210:3002` | 正式使用 |

> 對外公開的 URL 請洽詢 IT 團隊。

---

## 3. API Key 認證

大部分 API 需要在 Header 帶入 API Key：

```bash
# 設定變數（所有範例都會用到）
API="http://192.168.110.210:3003"
KEY="muser_test_apikey"
```

每個請求都要加上：

```bash
curl -H "X-API-Key: $KEY" "$API/..."
```

---

## 4. 常用功能 ①：註冊影片

將一支影片加入 Momentry 系統。系統會自動分析影片資訊（長度、fps、解析度）。

### 指令

```bash
curl -X POST -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  "$API/api/v1/files/register" \
  -d '{
    "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/你的影片.mp4"
  }'
```

### 回應說明

```json
{
  "success": true,
  "file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
  "file_name": "你的影片.mp4",
  "duration": 6785.0,
  "width": 1920,
  "height": 1080,
  "fps": 25.0,
  "message": "File registered successfully"
}
```

| 欄位 | 說明 |
|------|------|
| `file_uuid` | **最重要** — 這是影片的唯一 ID，之後所有查詢都用它 |
| `duration` | 影片長度（秒） |
| `fps` | 每秒影格數 |
| `message` | `"File registered successfully"` 表示成功 |

> ⚠️ `file_path` 必須是伺服器上實際存在的檔案路徑，不是你的本機路徑。

---

## 5. 常用功能 ②：查詢影片列表

看看目前系統裡有哪些影片。

### 指令

```bash
curl -H "X-API-Key: $KEY" "$API/api/v1/files/scan"
```

### 回應說明

```json
{
  "files": [
    {
      "name": "Charade.mp4",
      "path": "/data/demo/Charade.mp4",
      "size": 624701874,
      "is_registered": true,
      "file_uuid": "aeed71342a899fe4b4c57b7d41bcb692"
    },
    {
      "name": "demo.mov",
      "path": "/data/demo/demo.mov",
      "size": 234567890,
      "is_registered": false,
      "file_uuid": null
    }
  ],
  "total": 22,
  "registered_count": 20,
  "unregistered_count": 2
}
```

| 欄位 | 說明 |
|------|------|
| `files[].is_registered` | `true` = 已註冊，`false` = 尚未註冊 |
| `files[].file_uuid` | 已註冊的影片才有 uuid |
| `registered_count` | 已註冊的影片數量 |

---

## 6. 常用功能 ③：查詢影片詳細資料

取得特定影片的完整資訊。

### 指令

```bash
# 把 FILE_UUID 換成你的影片 ID
FILE_UUID="aeed71342a899fe4b4c57b7d41bcb692"

curl -H "X-API-Key: $KEY" "$API/api/v1/file/$FILE_UUID/probe"
```

### 回應說明

```json
{
  "file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
  "file_name": "Charade.mp4",
  "duration": 6785.0,
  "width": 1920,
  "height": 1080,
  "fps": 25.0,
  "total_frames": 169625,
  "streams": [
    { "codec_type": "video", "codec_name": "av1", "width": 1920, "height": 1080 },
    { "codec_type": "audio", "codec_name": "aac", "sample_rate": 44100, "channels": 2 }
  ]
}
```

### 解讀影片資訊

| 欄位 | 說明 |
|------|------|
| `duration` | 6785 秒 ≈ 113 分鐘 |
| `fps` | 每秒 25 張畫面 |
| `total_frames` | 總共 169,625 張畫面 |
| `streams[].codec_type` | `video` 或 `audio` |
| `streams[].codec_name` | 編碼格式（av1, h264, aac, opus） |

---

## 7. 常用功能 ④：搜尋對話內容

**這是最常用的功能！** 用關鍵字搜尋影片中的對話。

### 基本搜尋

```bash
curl -X POST -H "Content-Type: application/json" \
  "$API/api/v1/search/universal" \
  -d '{
    "query": "Cary Grant",
    "uuid": "aeed71342a899fe4b4c57b7d41bcb692",
    "limit": 5
  }'
```

### 回應說明

```json
{
  "query": "Cary Grant",
  "results": [
    {
      "type": "chunk",
      "score": 0.9,
      "text": "[59s-77s] Cast: Cary Grant, Walter Matthau.",
      "start_time": 59.0,
      "end_time": 77.0,
      "start_frame": 1475,
      "end_frame": 1925,
      "fps": 25.0
    },
    {
      "type": "chunk",
      "score": 0.9,
      "text": "[59s-302s] Cary Grant: \"loaded something constructive...\"",
      "start_time": 59.0,
      "end_time": 302.0,
      "start_frame": 1475,
      "end_frame": 7550,
      "fps": 25.0
    }
  ],
  "total": 3
}
```

### 搜尋技巧

| 搜尋類型 | 範例 | 說明 |
|---------|------|------|
| 人名 | `"Cary Grant"` | 搜尋演員名稱 |
| 對話引用 | `"how do you shave"` | 搜尋實際對話內容 |
| 電影名稱 | `"Charade"` | 搜尋影片標題 |
| 感謝用語 | `"thank you"` | 搜尋特定台詞 |

### 只搜尋特定類別

```bash
curl -X POST -H "Content-Type: application/json" \
  "$API/api/v1/search/universal" \
  -d '{
    "query": "Audrey Hepburn",
    "uuid": "aeed71342a899fe4b4c57b7d41bcb692",
    "types": ["chunk"],
    "limit": 3
  }'
```

---

## 8. 常用功能 ⑤：搜尋人物

查詢影片中出現過的人物。

### 指令

```bash
curl -H "X-API-Key: $KEY" "$API/api/v1/identities"
```

### 回應說明

```json
{
  "identities": [
    {
      "identity_uuid": "uuid-string",
      "name": "Cary Grant",
      "identity_type": "actor",
      "face_count": 120,
      "confidence": 0.95
    },
    {
      "identity_uuid": "uuid-string",
      "name": "Audrey Hepburn",
      "identity_type": "actor",
      "face_count": 85,
      "confidence": 0.92
    }
  ],
  "count": 41
}
```

### 查詢特定人物詳細資料

```bash
# 把 IDENTITY_UUID 換成上面查到的 uuid
IDENTITY_UUID="..."  

curl "$API/api/v1/identity/$IDENTITY_UUID"
```

---

## 9. 常用功能 ⑥：觀看影片

直接從瀏覽器串流播放影片。

### 網址格式

直接在瀏覽器網址列輸入：

```
http://192.168.110.210:3003/api/v1/file/aeed71342a899fe4b4c57b7d41bcb692/video
```

### 從特定時間開始播放

影片串流支援 HTTP Range，瀏覽器會自動處理。也可以用 `start` 參數：

```
http://192.168.110.210:3003/api/v1/file/aeed71342a899fe4b4c57b7d41bcb692/video?start=120
```

### 只看特定片段

```
http://192.168.110.210:3003/api/v1/file/aeed71342a899fe4b4c57b7d41bcb692/video?start=300&end=600
```

> 將 `3003` 改為 `3002` 即為正式環境。

---

## 10. 常用功能 ⑦：取得影片截圖

取得指定時間點的畫面截圖。

### 指令

```bash
curl -H "X-API-Key: $KEY" \
  "$API/api/v1/file/aeed71342a899fe4b4c57b7d41bcb692/thumbnail?frame=1475" \
  -o thumbnail.jpg
```

| 參數 | 說明 | 範例 |
|------|------|------|
| `frame` | 指定 frame 編號 | `1475`（約 59 秒 @ 25fps） |
| `x`, `y`, `w`, `h` | 裁切區域 | `?frame=1475&x=100&y=50&w=200&h=200` |

### 計算 frame 編號

```
frame = 時間(秒) × fps

例如：59秒 @ 25fps = 59 × 25 = 1475 frame
```

---

## 11. 進階功能：觸發影片處理

註冊影片後，需要觸發處理才能進行分析（語音轉文字、人臉偵測等）。

### 指令

```bash
curl -X POST -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  "$API/api/v1/file/aeed71342a899fe4b4c57b7d41bcb692/process" \
  -d '{
    "processors": ["asr", "cut", "yolo", "ocr", "face", "pose", "asrx"]
  }'
```

### 回應

```json
{
  "job_id": 140,
  "file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
  "status": "PENDING",
  "message": "Processing triggered"
}
```

### 處理器說明

| 處理器 | 功能 | 時間（全片 2 小時） |
|--------|------|-------------------|
| `cut` | 場景偵測 | ~2 秒 |
| `asr` | 語音轉文字 | ~30 分鐘 ⏳ 最久 |
| `asrx` | 語者辨識 | ~2 分鐘 |
| `face` | 人臉偵測 | ~10 分鐘 |
| `yolo` | 物體偵測 | ~30 分鐘 |
| `ocr` | 文字辨識 | ~15 分鐘 |
| `pose` | 姿勢估計 | ~15 分鐘 |

---

## 12. 進階功能：查詢處理進度

觸發處理後，可以用這個 API 查看進度。

### 指令

```bash
curl -H "X-API-Key: $KEY" \
  "$API/api/v1/progress/aeed71342a899fe4b4c57b7d41bcb692"
```

### 查詢 job 列表

```bash
curl -H "X-API-Key: $KEY" "$API/api/v1/jobs"
```

---

## 13. 常見問題

### Q1: 如何知道影片是否處理完成？

呼叫 `GET /api/v1/jobs`，看 `status` 是否為 `"completed"`。

### Q2: 搜尋不到我要的內容？

1. 確認影片已處理完成（job status = "completed"）
2. 確認 `uuid` 參數正確
3. 試試用英文搜尋（目前 ASR 預設為英文）
4. 試試更短的關鍵字

### Q3: 如何讓別人也能存取？

給他們 API Key 和 API 位址即可。API Key 請向 IT 團隊申請。

### Q4: 註冊失敗？

- 確認檔案路徑在伺服器上存在
- 確認檔案格式為 mp4 / mov / avi
- 錯誤訊息會提示原因

### Q5: 快速參考

```bash
# 一行搞定：設定變數後複製貼上
API="http://192.168.110.210:3003"
KEY="muser_test_apikey"
UUID="aeed71342a899fe4b4c57b7d41bcb692"

# 搜尋
curl -X POST -H "Content-Type: application/json" \
  "$API/api/v1/search/universal" \
  -d "{\"query\":\"搜尋關鍵字\",\"uuid\":\"$UUID\",\"limit\":3}" | jq '.results[] | {score, text}'
```

---

> **更多資訊**：完整 API 文件請參考 `docs_v1.0/API_V1.0.0/API_DOCUMENTATION.md`
