Enhanced video property validation in EmotionAnalyzer and EyeContactAnalyzer to handle invalid values and fallback mechanisms for frame count, FPS, and dimensions.
feba054 | # Behavior Analytics API Documentation | |
| ## Base URL | |
| All endpoints are prefixed with `/api` unless specified otherwise. | |
| ## Authentication Endpoints | |
| ### 1. OAuth2 Login | |
| - **URL**: `/api/auth/login` | |
| - **Method**: POST | |
| - **Input**: | |
| ```json | |
| { | |
| "username": "user@example.com", | |
| "password": "yourpassword" | |
| } | |
| ``` | |
| - **Output**: | |
| ```json | |
| { | |
| "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", | |
| "token_type": "bearer" | |
| } | |
| ``` | |
| ### 2. Email Login | |
| - **URL**: `/api/auth/login/email` | |
| - **Method**: POST | |
| - **Input**: | |
| ```json | |
| { | |
| "email": "user@example.com", | |
| "password": "yourpassword" | |
| } | |
| ``` | |
| - **Output**: | |
| ```json | |
| { | |
| "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", | |
| "token_type": "bearer" | |
| } | |
| ``` | |
| ### 3. Refresh Token | |
| - **URL**: `/api/auth/refresh` | |
| - **Method**: POST | |
| - **Input**: None (requires authenticated request with valid token) | |
| - **Output**: | |
| ```json | |
| { | |
| "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", | |
| "token_type": "bearer" | |
| } | |
| ``` | |
| ## User Endpoints | |
| ### 1. Create User | |
| - **URL**: `/api/users/` | |
| - **Method**: POST | |
| - **Input**: | |
| ```json | |
| { | |
| "email": "user@example.com", | |
| "first_name": "John", | |
| "last_name": "Doe", | |
| "password": "securepassword" | |
| } | |
| ``` | |
| - **Output**: | |
| ```json | |
| { | |
| "id": "uuid-string", | |
| "email": "user@example.com", | |
| "first_name": "John", | |
| "last_name": "Doe", | |
| "created_at": "2023-01-01T12:00:00.000Z", | |
| "is_active": true | |
| } | |
| ``` | |
| ### 2. Get Current User | |
| - **URL**: `/api/users/me` | |
| - **Method**: GET | |
| - **Input**: None (requires authenticated request) | |
| - **Output**: | |
| ```json | |
| { | |
| "id": "uuid-string", | |
| "email": "user@example.com", | |
| "first_name": "John", | |
| "last_name": "Doe", | |
| "created_at": "2023-01-01T12:00:00.000Z", | |
| "is_active": true | |
| } | |
| ``` | |
| ### 3. Get User by ID | |
| - **URL**: `/api/users/{user_id}` | |
| - **Method**: GET | |
| - **Input**: None (requires authenticated request) | |
| - **Output**: | |
| ```json | |
| { | |
| "id": "uuid-string", | |
| "email": "user@example.com", | |
| "first_name": "John", | |
| "last_name": "Doe", | |
| "created_at": "2023-01-01T12:00:00.000Z", | |
| "is_active": true | |
| } | |
| ``` | |
| ## Video Endpoints | |
| ### 1. Upload Video (Direct) | |
| - **URL**: `/api/videos/upload-direct` | |
| - **Method**: POST | |
| - **Input**: Multipart form data with file field | |
| - **Headers**: X-API-Key: your-api-key | |
| - **Output**: | |
| ```json | |
| { | |
| "video_id": "vid-12345", | |
| "original_filename": "example.mp4", | |
| "upload_date": "2023-01-01T12:00:00.000Z", | |
| "size": 12345678, | |
| "status": "uploaded", | |
| "duration": 120.5, | |
| "video_url": "/uploads/vid-12345.mp4" | |
| } | |
| ``` | |
| ### 2. Upload and Process Video (Direct) | |
| - **URL**: `/api/videos/upload-and-process-direct` | |
| - **Method**: POST | |
| - **Input**: Multipart form data with following fields: | |
| - file: The video file | |
| - frame_rate: integer (default 35) | |
| - language: string (default "en") | |
| - backend: string (default "mediapipe") | |
| - generate_annotated_video: boolean (default false) | |
| - model_name: string (default "gpt-4o") | |
| - **Headers**: X-API-Key: your-api-key | |
| - **Output**: | |
| ```json | |
| { | |
| "video_id": "vid-12345", | |
| "processing_results": { | |
| "emotion_data": {}, | |
| "transcript": "transcribed text...", | |
| "analysis": "analysis text...", | |
| "annotated_video_available": false, | |
| "emotion_percentages": {}, | |
| "overall_sentiment": "positive", | |
| "frame_emotions_count": 120, | |
| "overall_summary": "summary text...", | |
| "transcript_analysis": {}, | |
| "recommendations": {}, | |
| "body_language_analysis": {}, | |
| "body_language_data": {}, | |
| "eye_contact_analysis": {}, | |
| "eye_contact_data": {} | |
| }, | |
| "timing": { | |
| "upload_time": 1.23, | |
| "processing_time": 45.67, | |
| "total_time": 46.9 | |
| } | |
| } | |
| ``` | |
| ## Processing Endpoints | |
| ### 1. Process Video | |
| - **URL**: `/api/processing/direct` | |
| - **Method**: POST | |
| - **Input**: | |
| ```json | |
| { | |
| "video_id": "vid-12345", | |
| "frame_rate": 5, | |
| "language": "en", | |
| "backend": "opencv", | |
| "generate_annotated_video": false, | |
| "model_name": "gpt-4o" | |
| } | |
| ``` | |
| - **Headers**: X-API-Key: your-api-key | |
| - **Output**: | |
| ```json | |
| { | |
| "video_id": "vid-12345", | |
| "status": "processing", | |
| "progress": 0 | |
| } | |
| ``` | |
| ### 2. Get Processing Status | |
| - **URL**: `/api/processing/direct/status/{video_id}` | |
| - **Method**: GET | |
| - **Headers**: X-API-Key: your-api-key | |
| - **Output**: | |
| ```json | |
| { | |
| "video_id": "vid-12345", | |
| "status": "completed", | |
| "progress": 100, | |
| "error": null | |
| } | |
| ``` | |
| ### 3. Get Processing Results | |
| - **URL**: `/api/processing/direct/results/{video_id}` | |
| - **Method**: GET | |
| - **Headers**: X-API-Key: your-api-key | |
| - **Output**: | |
| ```json | |
| { | |
| "video_id": "vid-12345", | |
| "emotion_data": { | |
| "face_1": [ | |
| { | |
| "frame": 0, | |
| "emotions": { | |
| "happy": 0.8, | |
| "sad": 0.1, | |
| "angry": 0.05, | |
| "surprised": 0.05 | |
| }, | |
| "timestamp": 0.0 | |
| } | |
| ] | |
| }, | |
| "transcript": "transcribed text...", | |
| "analysis": "analysis text...", | |
| "annotated_video_available": false, | |
| "emotion_percentages": { | |
| "happy": 75, | |
| "sad": 15, | |
| "angry": 5, | |
| "surprised": 5 | |
| }, | |
| "overall_sentiment": "positive", | |
| "frame_emotions_count": 120, | |
| "overall_summary": "summary text...", | |
| "transcript_analysis": { | |
| "key_points": ["point 1", "point 2"], | |
| "sentiment": "positive" | |
| }, | |
| "recommendations": { | |
| "improvements": ["suggestion 1", "suggestion 2"] | |
| }, | |
| "body_language_analysis": { | |
| "summary": "body language summary", | |
| "key_observations": ["observation 1", "observation 2"] | |
| }, | |
| "body_language_data": { | |
| "timestamps": [0, 1, 2], | |
| "postures": ["standing", "gesturing", "seated"] | |
| }, | |
| "eye_contact_analysis": { | |
| "summary": "eye contact summary", | |
| "percentage": 85 | |
| }, | |
| "eye_contact_data": { | |
| "timestamps": [0, 1, 2], | |
| "looking_at_camera": [true, false, true] | |
| } | |
| } | |
| ``` | |
| ### 4. Get Processing Results (with user authentication) | |
| - **URL**: `/api/processing/results/{video_id}` | |
| - **Method**: GET | |
| - **Authorization**: Bearer token | |
| - **Output**: Same as `/api/processing/direct/results/{video_id}` | |
| ## Health Endpoints | |
| ### 1. Simple Health Check | |
| - **URL**: `/health` | |
| - **Method**: GET | |
| - **Input**: None | |
| - **Output**: | |
| ```json | |
| { | |
| "status": "ok" | |
| } | |
| ``` | |
| ### 2. API Health Check | |
| - **URL**: `/health/api` | |
| - **Method**: GET | |
| - **Input**: None | |
| - **Output**: | |
| ```json | |
| { | |
| "status": "healthy", | |
| "database": "connected", | |
| "api": "running" | |
| } | |
| ``` | |
| ## Root Endpoint | |
| ### 1. Root | |
| - **URL**: `/` | |
| - **Method**: GET | |
| - **Authorization**: Required (Bearer token or HF Space JWT) | |
| - **Output**: | |
| ```json | |
| { | |
| "status": "ok", | |
| "message": "Behavior Analytics API is running", | |
| "version": "1.0.0" | |
| } | |
| ``` |