# 📘 Momentry 身份管理 (Identity Management) API 實作指南

本文件示範如何透過 API 完成「從影片選擇 → 臉部分析 → 全域身份註冊」的完整流程。

## 1. 選擇目標影片

**目標**: 獲取系統中已註冊的影片列表，選擇要進行管理的影片。

**API**: `GET /api/v1/videos`

```bash
curl -s "http://127.0.0.1:3002/api/v1/videos" \
  -H "x-api-key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" | jq .
```

**回應範例**:
```json
{
  "videos": [
    {
      "uuid": "384b0ff44aaaa1f1",
      "file_name": "Old_Time_Movie_Show_-_Charade_1963.HD.mov",
      "duration": 6879.33
    },
    {
      "uuid": "9760d0820f0cf9a7",
      "file_name": "ExaSAN PCIe series - Director Ou.mp4",
      "duration": 159.64
    }
  ]
}
```
> **決策**: 我們選擇 `Charade 1963` (UUID: `384b0ff44aaaa1f1`) 進行管理。

---

## 2. 分析影片內的所有人物 (Faces / Persons / Speakers)

**目標**: 查看該影片內所有偵測到的「臉群 (Clusters)」。區分**已命名 (Named)**、**待命名 (Unregistered)** 與 **AI 建議**。

**API**: `GET /api/v1/videos/{uuid}/faces`

```bash
curl -s "http://127.0.0.1:3002/api/v1/videos/384b0ff44aaaa1f1/faces" \
  -H "x-api-key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" | jq .
```

**回應範例**:
```json
{
  "success": true,
  "video_uuid": "384b0ff44aaaa1f1",
  "total_faces": 6,
  "registered_count": 0,
  "unregistered_count": 6,
  "clusters": [
    {
      "cluster_id": "Person_4",
      "face_count": 45,
      "status": "unregistered", 
      "identity": {
        "name": "Cary Grant",
        "is_confirmed": true
      }
    },
    {
      "cluster_id": "Person_17",
      "face_count": 32,
      "status": "unregistered",
      "identity": {
        "name": "Audrey Hepburn",
        "is_confirmed": true
      }
    },
    {
      "cluster_id": "Person_12",
      "face_count": 10,
      "status": "unregistered",
      "identity": { "name": "Person_12" }
    },
    {
      "cluster_id": "Person_124",
      "face_count": 5,
      "status": "unregistered",
      "identity": null
    }
  ]
}
```

### 如何解讀結果？

| 欄位 | 說明 | 狀態 |
| :--- | :--- | :--- |
| **`identity.name`** | 若顯示具體人名 (如 "Audrey Hepburn")，代表 **已命名**。 | ✅ 待註冊 |
| **`identity.name`** | 若顯示 `Person_XX` (系統預設名)，代表 **待命名**。 | 🔄 等待 AI 或人工命名 |
| **`identity: null`** | 代表完全 **未識別**，通常數量較少。 | ❓ 待處理 |

---

## 3. 註冊全域身份 (Register Identity)

**目標**: 將已命名的人物升級為 **全域身份 (Global Identity)**。這能讓系統在其他影片中自動認出他們。

**API**: `POST /api/v1/person/{person_id}/register?video_uuid={uuid}`

### 3.1 註冊 Audrey Hepburn

```bash
curl -s -X POST "http://127.0.0.1:3002/api/v1/person/Person_17/register?video_uuid=384b0ff44aaaa1f1" \
  -H "x-api-key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" | jq .
```

**回應**:
```json
{
  "success": true,
  "message": "Successfully registered as global identity",
  "person_id": "Person_17",
  "name": "Audrey Hepburn",
  "face_identity_id": 12
}
```

### 3.2 註冊 Cary Grant

```bash
curl -s -X POST "http://127.0.0.1:3002/api/v1/person/Person_4/register?video_uuid=384b0ff44aaaa1f1" \
  -H "x-api-key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" | jq .
```

**回應**:
```json
{
  "success": true,
  "face_identity_id": 13,
  "name": "Cary Grant"
}
```

---

## ✅ 驗證成果

現在可以使用全域搜尋 API 確認身份是否註冊成功：

```bash
curl -s -X POST "http://127.0.0.1:3002/api/v1/identities/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: muser_..." \
  -d '{"query": "Audrey"}' | jq '.identities[] | {name: .profile.name, identity_id: .face_identity_id}'
```

**結果**:
```json
{
  "name": "Audrey Hepburn",
  "identity_id": 12
}
```

---

## 4. 擷取身份 / 人物 / 臉部 截圖

**目標**: 取得特定人物的臉部特寫截圖。
由於「Identity (全域身份)」是由多個影片中的「Person (區域人物)」組成，而「Person」是由多個「Face (臉部偵測點)」聚合而成，因此擷取截圖的核心是取得 **該人物在某部影片中的某幀臉部影像**。

**API**: `GET /api/v1/person/{person_id}/thumbnail`

### 參數說明

| 參數 | 類型 | 必填 | 說明 |
| :--- | :--- | :--- | :--- |
| `person_id` | Path | ✅ | 人物 ID (例如: `Person_17`) |
| `video_uuid` | Query | ✅ | 影片 UUID (用來定位影像源) |
| `index` | Query | ❌ | 指定第幾張臉 (預設 `0`) |

### 4.1 擷取 Audrey Hepburn 的臉部截圖 (預設第一張)

此指令會自動從 `Charade 1963` 影片中擷取 Audrey Hepburn 最清晰的一張臉，並儲存為 `audrey.jpg`。

```bash
curl -s -o audrey.jpg \
  "http://127.0.0.1:3002/api/v1/person/Person_17/thumbnail?video_uuid=384b0ff44aaaa1f1" \
  -H "x-api-key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
```

> **注意**: 回應是 **圖片二進位資料 (JPG)**，請使用 `-o filename.jpg` 儲存，**不要**使用 `| jq`。

### 4.2 擷取 Cary Grant 的其他臉部截圖 (指定 Index)

若你想看同一人物的其他角度，可以調整 `index` 參數。
假設 Cary Grant (`Person_4`) 在影片中出現了 45 次：

```bash
# 擷取第 5 次出現的臉部截圖 (index 從 0 開始)
curl -s -o cary_face_5.jpg \
  "http://127.0.0.1:3002/api/v1/person/Person_4/thumbnail?video_uuid=384b0ff44aaaa1f1&index=4" \
  -H "x-api-key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
```

### 4.3 Identity (全域身份) 的截圖策略

由於全域 Identity (`face_identity_id: 12`) 跨越多部影片，要取得它的截圖，請先查詢它所屬的影片：

1. **查詢 Identity 所在的影片**:
   ```bash
   curl -s "http://127.0.0.1:3002/api/v1/identities/12/videos" \
     -H "x-api-key: muser_..." | jq '.videos[0].video_uuid'
   ```
2. **取得該影片中的對應 Person ID**: 從上一步結果中找到 `person_id` (例如 `Person_17`)。
3. **呼叫截圖 API**: 使用該 `video_uuid` 和 `person_id` 呼叫上述截圖 API。

