Skip to content

API_GUIDE_EN.md

Latest commit

ย 

History

History
357 lines (286 loc) ยท 6.96 KB

API_GUIDE_EN.md

File metadata and controls

357 lines (286 loc) ยท 6.96 KB

Face Recognition API Guide

๐Ÿš€ Starting the Server

Method 1: Using app.py (Recommended)

cd backend
python app.py --mode server

Method 2: Running server.py Directly

cd backend
python server.py

Method 3: Running Uvicorn Directly

cd backend
uvicorn server:app --host 0.0.0.0 --port 8000 --reload

๐Ÿ“ก Connection Information

๐Ÿ“š API Endpoints

1. Health Check

Check system status

GET /api/health

Response Example:

{
  "status": "healthy",
  "model_info": {
    "model_name": "buffalo_l",
    "device": "cpu",
    "embedding_size": 512,
    "det_size": [640, 640]
  },
  "database_info": {
    "total_faces": 5,
    "total_recognitions": 120,
    "threshold": 0.5
  }
}

2. Face Registration

Register a new face in the database

POST /api/face/register
Content-Type: multipart/form-data

Parameters:

  • name (string, required): Name of the person to register
  • file (file, required): Face image file (JPEG, PNG)

cURL Example:

curl -X POST "http://localhost:8000/api/face/register" \
  -F "name=ํ™๊ธธ๋™" \
  -F "file=@/path/to/photo.jpg"

Python Example:

import requests

url = "http://localhost:8000/api/face/register"
files = {"file": open("photo.jpg", "rb")}
data = {"name": "ํ™๊ธธ๋™"}

response = requests.post(url, files=files, data=data)
print(response.json())

Response Example (Success):

{
  "success": true,
  "face_id": "person_20260206_153045",
  "name": "ํ™๊ธธ๋™",
  "message": "'ํ™๊ธธ๋™' ์–ผ๊ตด์ด ์„ฑ๊ณต์ ์œผ๋กœ ๋“ฑ๋ก๋˜์—ˆ์Šต๋‹ˆ๋‹ค."
}

Response Example (Failure - Face Detection Failed):

{
  "success": false,
  "face_id": null,
  "name": null,
  "message": "์ด๋ฏธ์ง€์—์„œ ์–ผ๊ตด์„ ๊ฐ์ง€ํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. ๋‹ค๋ฅธ ์ด๋ฏธ์ง€๋ฅผ ์‹œ๋„ํ•ด์ฃผ์„ธ์š”."
}

3. Face List

Retrieve all registered face information

GET /api/faces/list

cURL Example:

curl -X GET "http://localhost:8000/api/faces/list"

Response Example:

{
  "total": 3,
  "faces": [
    {
      "face_id": "person_20260206_153045",
      "name": "ํ™๊ธธ๋™",
      "registered_at": "2026-02-06T15:30:45.123456",
      "last_seen": "2026-02-06T16:20:10.654321",
      "recognition_count": 25,
      "image_path": "faces/person_20260206_153045.jpg"
    },
    {
      "face_id": "person_20260206_140530",
      "name": "๊น€์ฒ ์ˆ˜",
      "registered_at": "2026-02-06T14:05:30.789012",
      "last_seen": null,
      "recognition_count": 0,
      "image_path": "faces/person_20260206_140530.jpg"
    }
  ]
}

4. Delete Face

Delete a registered face

DELETE /api/face/{face_id}

Parameters:

  • face_id (path parameter, required): Face ID to delete

cURL Example:

curl -X DELETE "http://localhost:8000/api/face/person_20260206_153045"

Response Example (Success):

{
  "success": true,
  "face_id": "person_20260206_153045",
  "message": "์–ผ๊ตด ID 'person_20260206_153045'๊ฐ€ ์„ฑ๊ณต์ ์œผ๋กœ ์‚ญ์ œ๋˜์—ˆ์Šต๋‹ˆ๋‹ค."
}

Response Example (Failure):

{
  "detail": "์–ผ๊ตด ID 'invalid_id'๋ฅผ ์ฐพ์„ ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค."
}

5. Real-time Video Streaming

Real-time face recognition video stream

GET /api/camera/stream

Usage:

Using in HTML:

<!DOCTYPE html>
<html>
<head>
    <title>์–ผ๊ตด ์ธ์‹ ์ŠคํŠธ๋ฆฌ๋ฐ</title>
</head>
<body>
    <h1>์‹ค์‹œ๊ฐ„ ์–ผ๊ตด ์ธ์‹</h1>
    <img src="http://localhost:8000/api/camera/stream"
         alt="Video Stream"
         width="640"
         height="480">
</body>
</html>

Using in React:

function VideoStream() {
  return (
    <div>
      <h1>์‹ค์‹œ๊ฐ„ ์–ผ๊ตด ์ธ์‹</h1>
      <img
        src="http://localhost:8000/api/camera/stream"
        alt="Video Stream"
        width={640}
        height={480}
      />
    </div>
  );
}

Features:

  • Streaming in MJPEG format
  • Real-time face detection and recognition
  • Registered faces: Green box + name + confidence score
  • Unregistered faces: Red box + "Unknown"

๐Ÿ”ง Test Scenarios

1. Basic Operation Test

# 1. Health check
curl http://localhost:8000/api/health

# 2. Register face (using test image)
curl -X POST "http://localhost:8000/api/face/register" \
  -F "name=ํ…Œ์ŠคํŠธ" \
  -F "file=@test_image.jpg"

# 3. Check face list
curl http://localhost:8000/api/faces/list

# 4. Check video stream (in browser)
# http://localhost:8000/api/camera/stream

2. Python Client Example

import requests
import json

# Server address
BASE_URL = "http://localhost:8000"

# 1. Health check
response = requests.get(f"{BASE_URL}/api/health")
print("ํ—ฌ์Šค์ฒดํฌ:", json.dumps(response.json(), indent=2, ensure_ascii=False))

# 2. Register face
with open("photo.jpg", "rb") as f:
    files = {"file": f}
    data = {"name": "ํ™๊ธธ๋™"}
    response = requests.post(f"{BASE_URL}/api/face/register", files=files, data=data)
    print("๋“ฑ๋ก ๊ฒฐ๊ณผ:", json.dumps(response.json(), indent=2, ensure_ascii=False))

# 3. Retrieve face list
response = requests.get(f"{BASE_URL}/api/faces/list")
faces = response.json()
print(f"๋“ฑ๋ก๋œ ์–ผ๊ตด ์ˆ˜: {faces['total']}")
for face in faces['faces']:
    print(f"  - {face['name']} (ID: {face['face_id']})")

# 4. Delete face
face_id = "person_20260206_153045"
response = requests.delete(f"{BASE_URL}/api/face/{face_id}")
print("์‚ญ์ œ ๊ฒฐ๊ณผ:", json.dumps(response.json(), indent=2, ensure_ascii=False))

๐Ÿ› Troubleshooting

Issue: Camera not found

Solution:
- Check if the camera is connected
- Check if another program is using the camera
- Change camera_id in backend/api/routes.py (default: 0)

Issue: Model download error

Solution:
- Check internet connection
- InsightFace model downloads automatically (~200MB)
- First run may take some time

Issue: CORS error

Solution:
- Add frontend URL to origins list in backend/server.py
- Clear browser cache and retry

Issue: Low face recognition accuracy

Solution:
- Shoot in a well-lit location
- Use frontal face photos
- Use high-resolution images
- Adjust threshold value in backend/models/face_database.py (default: 0.5)

๐Ÿ“Š Performance Optimization

GPU Acceleration (Optional)

Use GPU acceleration on systems with CUDA installed:

pip uninstall onnxruntime
pip install onnxruntime-gpu

Threshold Adjustment

Adjust face recognition threshold (backend/models/face_database.py):

# Stricter matching (reduce false positives)
database = FaceDatabase(threshold=0.6)

# More lenient matching (reduce false negatives)
database = FaceDatabase(threshold=0.4)

๐Ÿ“ Additional Information

Written: 2026-02-06 Version: 1.0.0