# Face, Speaker, Person, Identity API 教學示範

本文件將以 1963 年電影《Charade》（謎中謎）為例，示範如何使用 API 管理 **Face** (臉孔)、**Person** (影片中的角色實體) 與 **Identity** (真實身份)。

## 核心概念定義

在開始之前，請區分以下名詞：

1. **Face (臉孔)**: 影像中偵測到的具體臉部特徵數據（向量）。
2. **Person (角色實體)**: 在特定影片中出現的角色。他是 Face + Speaker (說話者) 的集合體。
    * *例如：影片 `384b0ff44aaaa1f14cb2cd63b3fea966` 中的 `Person_17`。*
3. **Identity (真實身份)**: 跨越所有影片的全域實體（如真實演員或新聞人物）。
    * *例如：Cary Grant, Audrey Hepburn。*

---

## 前置準備

* **API URL**: `http://localhost:3003`
* **API Key**: `/`
* **目標影片 (Video UUID)**: `384b0ff44aaaa1f14cb2cd63b3fea966` (Charade)

---

## 情境設定

我們要在影片中識別兩位主角：
1. **Audrey Hepburn** (飾演 Reggie Lampert)
2. **Cary Grant** (飾演 Peter Joshua)

---

## 步驟一：查看影片中的現有角色 (Person List)

首先，我們查詢系統在影片中偵測到了哪些人物 (Person)。

```bash
curl -s "http://localhost:3003/api/v1/person/list?file_uuid=384b0ff44aaaa1f14cb2cd63b3fea966&limit=5" \
  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
  | python3 -m json.tool
```

**預期回應**：
你會看到類似如下的列表，其中包含系統自動分配的 `person_id` (例如 `Person_17`, `Person_4` 等)。

```json
{
    "persons": [
        {
            "person_id": "Person_17",
            "name": null,
            "speaker_id": "SPEAKER_1",
            "appearance_count": 1636
        },
        {
            "person_id": "Person_4",
            "name": null,
            "speaker_id": "SPEAKER_0",
            "appearance_count": 936
        }
    ]
}
```

---

## 步驟二：建立身份並綁定角色 (Register Identity from Person)

假設經過人工確認，我們知道 `Person_17` 是 Audrey Hepburn。我們可以使用單一 API 同時完成 **「建立 Identity」** 與 **「綁定 Person」** 兩個動作。

### 範例 1: 註冊 Audrey Hepburn

我們指定 `Person_17` 為 "Audrey Hepburn"。系統會檢查此 Identity 是否存在；若不存在則建立，若已存在則直接綁定。

```bash
curl -s -X POST "http://localhost:3003/api/v1/identities/from-person" \
  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
  -H "Content-Type: application/json" \
  -d '{
    "file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
    "person_id": "Person_17",
    "identity_name": "Audrey Hepburn",
    "metadata": { "role": "Reggie Lampert" }
  }' | python3 -m json.tool
```

**預期回應**：

```json
{
    "success": true,
    "message": "Successfully registered identity 'Audrey Hepburn' and linked to person 'Person_17'",
    "identity_id": 10, 
    "identity_name": "Audrey Hepburn",
    "person_id": "Person_17"
}
```

*(註：此操作會自動將該影片中 `Person_17` 的名稱更新為 "Audrey Hepburn")*

### 範例 2: 註冊 Cary Grant

假設 `Person_4` 是 Cary Grant，我們進行同樣的操作。

```bash
curl -s -X POST "http://localhost:3003/api/v1/identities/from-person" \
  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
  -H "Content-Type: application/json" \
  -d '{
    "file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
    "person_id": "Person_4",
    "identity_name": "Cary Grant",
    "metadata": { "role": "Peter Joshua" }
  }' | python3 -m json.tool
```

**預期回應**：

```json
{
    "success": true,
    "message": "Successfully registered identity 'Cary Grant' and linked to person 'Person_4'",
    "identity_id": 11,
    "identity_name": "Cary Grant",
    "person_id": "Person_4"
}
```

---

## 步驟三：查看全域身份庫 (List Identities)

現在我們可以查看所有已建立的「真實身份」，這些身份是跨影片通用的。

```bash
curl -s "http://localhost:3003/api/v1/identities?limit=10" \
  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
  | python3 -m json.tool
```

**預期回應**：
你應該能看到剛剛建立的 "Audrey Hepburn" 和 "Cary Grant"。

```json
[
    {
        "id": 11,
        "name": "Cary Grant",
        "metadata": { "role": "Peter Joshua" }
    },
    {
        "id": 10,
        "name": "Audrey Hepburn",
        "metadata": { "role": "Reggie Lampert" }
    }
]
```

---

## 步驟四：驗證綁定結果

再次查詢影片中的 `Person` 列表，確認名稱是否已自動更新。

```bash
curl -s "http://localhost:3003/api/v1/person/list?file_uuid=384b0ff44aaaa1f14cb2cd63b3fea966&limit=5" \
  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
  | python3 -m json.tool
```

**預期結果**：
原本的 `Person_17` 現在應該顯示為 `"name": "Audrey Hepburn"`。

---

## 常見問題 (FAQ)

**Q: 如果我想把「現有的 Person」綁定到「已經存在的 Identity」，要怎麼做？**
A: 使用相同的 `POST /api/v1/identities/from-person` API。只要傳入相同的 `identity_name` (例如 "Audrey Hepburn")，系統會自動找到該 Identity 並將新的 Person 連結過去，不會建立重複的 Identity。

**Q: Identity 和 Person 的差別是什麼？**
A: **Identity** 是真實世界的人（例如 "Tom Hanks"），這是全域共享的。
**Person** 是他在某部電影裡的具體出現（例如《阿甘正傳》裡的阿甘）。一個 Identity 可以對應多個影片中的多個 Person。
