---
title: Gesture Detection & Identity Validation API
emoji: 👋
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit
app_port: 7860
---

# 👋 Gesture Detection & Identity Validation API


A unified API for gesture detection in videos and identity validation using facial recognition and gesture verification.

## 🚀 Features

- **Gesture Detection**: Detect and track hand gestures in video files
- **Identity Validation**: Validate user identity using facial recognition and required gestures
- **Real-time Processing**: Efficient video processing with configurable frame skip
- **RESTful API**: Clean, documented API endpoints

## 📋 API Endpoints

### `GET /`
Get API information and available endpoints

### `GET /health`
Health check endpoint showing service status

### `POST /gestures`
Detect gestures in an uploaded video file

**Parameters:**
- `video` (file): Video file to process
- `frame_skip` (int, optional): Number of frames to skip (default: 1)

**Response:**
```json
{
  "gestures": [
    {
      "gesture": "thumbs_up",
      "duration": 45,
      "confidence": 0.92
    }
  ]
}
```

### `POST /validate`
Validate user identity using facial recognition and gesture verification

**Parameters:**
- `photo` (file): ID document photo
- `video` (file): User video containing face and gestures
- `gestures` (JSON array): Required gestures (e.g., `["thumbs_up","peace"]`)
- `error_margin` (float, optional): Error margin for validation (default: 0.33)
- `require_all_gestures` (bool, optional): Whether all gestures must be present
- `similarity_threshold` (float, optional): Facial similarity threshold
- `include_details` (bool, optional): Include detailed validation results

**Response:**
```json
{
  "face": true,
  "gestures": true,
  "overall": true,
  "status": "success",
  "processing_time_ms": 6925,
  "timestamp": "2025-09-30T08:30:22Z"
}
```

## 🎯 Supported Gestures

- `thumbs_up` (👍)
- `peace` (✌️)
- `ok_sign` (👌)
- `open_palm` (👋)
- `call_me` (🤙)
- `grabbing` (✊)

## 📖 Documentation

Interactive API documentation is available at:
- **Swagger UI**: `/docs`
- **ReDoc**: `/redoc`

## 🔧 Usage Example

```bash
# Detect gestures in a video
curl -X POST http://localhost:7860/gestures \
  -F "video=@my_video.mp4" \
  -F "frame_skip=3"

# Validate identity
curl -X POST http://localhost:7860/validate \
  -F "photo=@id_photo.jpg" \
  -F "video=@user_video.mp4" \
  -F 'gestures=["thumbs_up","peace"]' \
  -F "include_details=true"
```

## 🏗️ Technology Stack

- **Framework**: FastAPI
- **ML Models**: ONNX Runtime
- **Computer Vision**: OpenCV
- **Tracking**: OCSort with Kalman filters
- **Facial Recognition**: Custom embeddings module

## 📝 Note

Facial validation is currently in placeholder mode and always returns success. Gesture validation is fully functional.

## 📄 License

MIT License - See LICENSE file for details

## 🔗 Links

- [GitHub Repository](https://github.com/kybtech/gesture-detection)
- [API Documentation](/docs)
- [Hugging Face Space](https://huggingface.co/spaces/algoryn/validation)