QFace SDK / Examples

1. Edge device — Python（攝影機 → 識別）

邊緣設備拿 API Key 後最小範例。每 2 秒抓幀識別，匹配時印出人員名。

import time, cv2, requests

API   = "https://qface.bluesign.com.tw"
KEY   = "qf_xxx...your_device_api_key"    # 設備建立時取得

cap = cv2.VideoCapture(0)
sess = requests.Session()
sess.headers["X-Device-Key"] = KEY

# Heartbeat once
sess.post(f"{API}/api/devices/heartbeat", headers={"X-Device-Version":"v1.0"})

while True:
    ok, frame = cap.read()
    if not ok: break
    ok, buf = cv2.imencode(".jpg", frame, [cv2.IMWRITE_JPEG_QUALITY, 85])
    r = sess.post(f"{API}/api/recognize", files={"image": ("frame.jpg", buf.tobytes(), "image/jpeg")})
    j = r.json()
    if j.get("matched"):
        print(f"[{time.strftime('%H:%M:%S')}] {j['name']} ({j['score']:.3f})")
    elif j.get("reason") == "no_face":
        pass  # quiet
    else:
        print(f"[{time.strftime('%H:%M:%S')}] no match, {j.get('elapsed_ms')}ms")
    time.sleep(2.0)

2. Edge device — 純瀏覽器 (HTML + JS)

不寫 Python 也行 — 任何能跑瀏覽器的裝置都能當識別點。完整範例參考 /demo.html 或 「現場辨識」頁。

const stream = await navigator.mediaDevices.getUserMedia({video:true});
video.srcObject = stream;
setInterval(async () => {
  canvas.getContext('2d').drawImage(video, 0, 0, video.videoWidth, video.videoHeight);
  const blob = await new Promise(r => canvas.toBlob(r, 'image/jpeg', 0.85));
  const fd = new FormData(); fd.append('image', blob, 'frame.jpg');
  const r = await fetch('/api/recognize', {
    method:'POST', body: fd,
    headers: { 'X-Device-Key': 'qf_xxx...your_device_api_key' }
  });
  const j = await r.json();
  if (j.matched) console.log(j.name, j.score);
}, 2000);

3. 批次匯入 ZIP 格式

上傳到 POST /api/personnel/bulk。ZIP 內必須包含 manifest.csv 與所有照片。

manifest.csv 範例：

name,photo,external_id,note
陳威 (Chen Wei),photos/chen.jpg,EMP-001,工程部
林承 (Lin Cheng),photos/lin.jpg,EMP-002,
王梅 (Wang Mei),photos/wang.jpg,EMP-003,人資部

ZIP 結構：

my_import.zip
├── manifest.csv
└── photos/
    ├── chen.jpg
    ├── lin.jpg
    └── wang.jpg

上傳方式：

curl -X POST https://qface.bluesign.com.tw/api/personnel/bulk \
  -F "archive=@my_import.zip" \
  -F "tenant_id=alpha"

回傳 {total, enrolled, results:[{row, name, status, personnel_id?, reason?}]}。前端也可直接從人員管理頁的「批次匯入 CSV」按鈕上傳。

4. 端點速查