API 문서

X-License-Key: <회사코드>

curl -X POST https://facematch.team1985.com/api/register \
  -H "X-License-Key: <회사코드>" \
  -F files=@front.jpg -F files=@lu.jpg -F files=@ru.jpg \
  -F files=@ld.jpg -F files=@rd.jpg \
  -F poses=frontal,left_up,right_up,left_down,right_down \
  -F unique_key=member-1024 \
  -F group_key=A \
  -F extra='{"name":"홍길동","mobile":"01012345678"}'

{
  "status": "success",
  "action": "inserted",   // 또는 "updated"
  "face_id": 12,
  "unique_key": "member-1024",
  "group_key": "A",
  "received": 5,   // 받은 이미지 수
  "accepted": 5,   // 품질게이트 통과·저장 수
  "poses": ["frontal","left_up","right_up","left_down","right_down"],
  "face": {
    "bbox": [142,88,320,300],
    "det_score": 0.99
  }
}

curl -X POST https://facematch.team1985.com/api/detect \
  -H "X-License-Key: <회사코드>" \
  -F file=@photo.jpg \
  -F group_key=A

{
  "status": "success",
  "recognized": true,
  "similarity": 0.987,   // 1위 유사도
  "similarity2": 0.141,  // 2위 유사도
  "gap": 0.846,          // 1-2위 차이
  "ambiguous": false,    // 닮은 사람과 구분 애매 여부
  "verified_by": null,      // 2차 모델(buffalo_l)로 확정 시 모델명, 아니면 null
  "threshold": 0.35,
  "margin": 0.05,
  "elapsed_ms": 176,
  "person": {
    "id": 12,
    "unique_key": "member-1024",
    "group_key": "A",
    "extra": { "name": "홍길동", "mobile": "01012345678" }
  },
  "num_faces_in_frame": 1
}

{
  "status": "success",
  "recognized": false,   // 자동 확정 안 함
  "ambiguous": true,
  "verified_by": null,
  "gap": 0.012,
  "message": "닮은 사람과 구분이 어렵습니다. 한 번 더 촬영해 주세요.",
  "candidates": [       // '이 중 하나' 후보(top-2)
    { "unique_key": "member-1024", "group_key": "A",
      "extra": { "name": "홍길동" }, "similarity": 0.712 },
    { "unique_key": "member-1025", "group_key": "A",
      "extra": { "name": "홍길순" }, "similarity": 0.700 }
  ]
}

• candidates는 ambiguous: true일 때만 포함됩니다.
• 각 후보 형태는 person과 동일 + similarity(유사도) 추가.
• recognized는 여전히 false — 서버는 자동 확정하지 않습니다.
• 후보로 최종 선택 UI를 만들지, 재촬영을 유도할지는 도입사 정책입니다.
• 기존 앱은 모르는 필드를 무시하므로 하위호환됩니다.

curl -X POST https://facematch.team1985.com/api/multi-detect \
  -H "X-License-Key: <회사코드>" \
  -F file=@crowd.jpg

{
  "status": "success",
  "num_faces": 3,
  "recognized_count": 2,
  "elapsed_ms": 880,
  "faces": [
    {
      "recognized": true,
      "similarity": 0.987,
      "person": {
        "unique_key": "member-1024",
        "extra": { "name": "홍길동" }
      },
      "bbox": [88,60,240,250]
    },
    {
      "recognized": false,
      "similarity": 0.21,
      "person": null,
      "bbox": [410,90,560,270]
    }
  ]
}

curl https://facematch.team1985.com/api/faces \
  -H "X-License-Key: <회사코드>"

{
  "status": "success",
  "list": [
    {
      "id": 12,
      "unique_key": "member-1024",
      "group_key": "A",
      "extra": { "name": "홍길동", "mobile": "01012345678" },
      "name": "홍길동",
      "mobile": "01012345678",
      "image_path": "/images/reg_....jpg",
      "created_at": 1782301234
    }
  ]
}

curl https://facematch.team1985.com/api/faces/12/poses \
  -H "X-License-Key: <회사코드>"

{
  "status": "success",
  "unique_key": "member-1024",
  "group_key": "A",
  "extra": { "name": "홍길동" },
  "list": [
    { "pose": "frontal", "image_path": "/images/...", "quality": 312.5 },
    { "pose": "left_up", "image_path": "/images/...", "quality": 287.1 }
  ]
}

curl -X POST https://facematch.team1985.com/api/faces/12 \
  -H "X-License-Key: <회사코드>" \
  -F name=홍길동 -F mobile=01012345678

curl -X DELETE "https://facematch.team1985.com/api/faces/by-key/member-1024?group_key=gangnam" \
  -H "X-License-Key: <회사코드>"

# 응답
{ "status": "success", "deleted": 1, "face_ids": [12] }

curl -X DELETE https://facematch.team1985.com/api/faces/12 \
  -H "X-License-Key: <회사코드>"

curl -X POST https://facematch.co.kr/api/sonic/zones \
  -H "X-License-Key: <회사코드>" \
  -F zone_key=gangnam-1f-entrance \
  -F "name=1층 입구" \
  -F place_name=강남점 \
  -F campaign=여름세일

{
  "status": "success",
  "action": "inserted",   // 또는 "updated"
  "zone_key": "gangnam-1f-entrance",
  "zone_id": 1001    // 서버가 배정한 방송용 ID
}

curl https://facematch.co.kr/api/sonic/zones \
  -H "X-License-Key: <회사코드>"

{
  "status": "success",
  "zones": [
    {
      "zone_id": 1001,
      "zone_key": "gangnam-1f-entrance",
      "name": "1층 입구",
      "place_name": "강남점",
      "campaign": "여름세일"
    }
  ]
}

curl "https://facematch.co.kr/api/sonic/zones/by-key/gangnam-1f-entrance/wav?minutes=10" \
  -H "X-License-Key: <회사코드>" \
  -o zone_gangnam_1f.wav

curl -X DELETE https://facematch.co.kr/api/sonic/zones/by-key/gangnam-1f-entrance \
  -H "X-License-Key: <회사코드>"

# 응답
{ "status": "success", "deleted": 1, "zone_id": 1001 }

curl -X POST https://facematch.co.kr/api/sonic/event \
  -H "Content-Type: application/json" \
  -d '{
    "license_key": "<회사코드>",
    "device_id": "a3f9-...",
    "zone_id": 1001,
    "event": "enter",
    "entered_at": 1787570000
  }'

curl -X POST https://facematch.co.kr/api/sonic/event \
  -H "Content-Type: application/json" \
  -d '{
    "license_key": "<회사코드>",
    "device_id": "a3f9-...",
    "zone_id": 1001,
    "event": "exit",
    "entered_at": 1787570000,
    "last_seen_at": 1787570120,
    "dwell_sec": 120,
    "frame_count": 70,
    "avg_snr_db": 19.4
  }'

curl "https://facematch.team1985.com/api/logs?limit=50" \
  -H "X-License-Key: <회사코드>"

{
  "status": "success",
  "list": [
    {
      "id": 224,
      "mode": "detect",   // detect | multi
      "recognized": true,
      "name": "홍길동",
      "unique_key": "member-1024",
      "group_key": "A",
      "similarity": 0.723,
      "threshold": 0.35,
      "matched_pose": "left_up",
      "probe_image": "/images/probe_....jpg",
      "matched_image": "/images/reg_....jpg",
      "elapsed_ms": 180,
      "num_faces": 1,
      "created_at": 1782301234
    }
  ]
}