會同 AI 眼鏡模式

最小串接流程

眼鏡端只需要：登入拿 token → 擷取鏡頭 JPEG → 上傳辨識 → 把結果顯示/播報。

• Base URL：https://huitong-face.100thy.com
• Auth header：Authorization = Bearer token_value
• 建議頻率：每 2–4 秒一張；有本地 face detection 時，只在看到人臉後上傳。

1. 登入取得 Token

POST /api/auth/login
Content-Type: application/json

{
  "username": "<device_or_user_account>",
  "password": "<password>"
}

Response
{
  "token": "eyJ...",
  "user": { "id": 1, "username": "1", "is_admin": 1 }
}

2. 上傳眼鏡畫面辨識

POST /api/faces/identify
Authorization: Bearer token_value
Content-Type: multipart/form-data

Form field:
image = frame.jpg  // JPEG, 建議寬度 480–720px, quality 0.75–0.9

TOKEN='登入回傳的 token'
curl -X POST 'https://huitong-face.100thy.com/api/faces/identify' \
  -H "Authorization: Bearer $TOKEN" \
  -F 'image=@frame.jpg;type=image/jpeg'

3. 辨識結果處理

{
  "match": {
    "person": {
      "id": 12,
      "name": "王小明",
      "tags": "朋友,客戶",
      "created_at": "2026-06-28T00:00:00+00:00"
    },
    "score": 0.873,
    "confidence_percent": 87
  },
  "threshold": 0.42
}

眼鏡端建議：HUD 顯示姓名、標籤、信心百分比；TTS 播報「這個人可能是王小明，信心大約 87%」。score 是相似度，對使用者請說「信心/相似度」，不要說成絕對機率。

No match
{
  "match": null,
  "best_score": 0.31,
  "confidence_percent": 31,
  "threshold": 0.42
}

4. Web / JavaScript 範例

const BASE = 'https://huitong-face.100thy.com';
let token = '';

async function login(username, password) {
  const r = await fetch(`${BASE}/api/auth/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username, password })
  });
  if (!r.ok) throw new Error(await r.text());
  token = (await r.json()).token;
}

async function identifyFrame(jpegBlob) {
  const fd = new FormData();
  fd.append('image', jpegBlob, 'frame.jpg');
  const r = await fetch(`${BASE}/api/faces/identify`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}` },
    body: fd
  });
  if (r.status === 401) { /* 重新登入後重試 */ }
  if (!r.ok) throw new Error(await r.text());
  return await r.json();
}

5. 可選：記住新人

POST /api/people/enroll
Authorization: Bearer token_value
Content-Type: multipart/form-data

name = 王小明
tags = 朋友,客戶
consent_text = demo consent
face_images = face_1.jpg
face_images = face_2.jpg
face_images = face_3.jpg

正式眼鏡端可用語音取得姓名/標籤，連拍 3–5 張穩定樣本後送出。服務端只負責記憶與辨識；眼鏡端負責相機、TTS、HUD、冷卻與離線重試。

錯誤與重試

• 401：token 過期或錯誤，重新登入。
• 422：畫面沒有可用人臉或圖片格式不適合，換下一張 frame。
• 500/502：服務忙碌或後端錯誤，退避 2–5 秒再試。
• 同一個人建議 10–30 秒內不要重複播報，避免眼鏡一直講話。