Spaces:
Paused
Paused
| title: FunCaptcha Solver API | |
| emoji: 🧩 | |
| colorFrom: blue | |
| colorTo: purple | |
| sdk: docker | |
| pinned: false | |
| suggested_hardware: cpu-basic | |
| app_file: app.py | |
| # 🧩 FunCaptcha Solver API - Hugging Face Spaces | |
| > **High-performance FunCaptcha solver dengan fuzzy matching dan API key authentication** | |
| ## 🚀 Features | |
| - ✅ **FastAPI** - High performance async web framework | |
| - ✅ **Docker optimization** - Multi-stage build untuk size minimal | |
| - ✅ **Fuzzy label matching** - Handle variasi label seperti "ice cream" vs "ice" | |
| - ✅ **API key authentication** - Secure access menggunakan HF Secrets | |
| - ✅ **Response caching** - Fast responses untuk requests yang sama | |
| - ✅ **Multi-model support** - Support berbagai jenis CAPTCHA challenges | |
| - ✅ **Memory efficient** - Optimized untuk HF Spaces environment | |
| - ✅ **Auto health checks** - Built-in monitoring | |
| ## 📋 Supported Challenge Types | |
| | Challenge Type | Description | Response | | |
| |---|---|---| | |
| | `pick_the` | Pick specific objects dari images | `{status, box, confidence}` | | |
| | `upright` | Find correctly oriented objects | `{status, button_index, confidence}` | | |
| ## 🔧 Deployment ke Hugging Face Spaces | |
| ### 1. Create New Space | |
| 1. Buka [Hugging Face Spaces](https://huggingface.co/spaces) | |
| 2. Click **"Create new Space"** | |
| 3. Pilih: | |
| - **Space name**: `funcaptcha-solver-api` (atau nama pilihan Anda) | |
| - **License**: `mit` | |
| - **Space SDK**: `Docker` | |
| - **Space visibility**: `Private` (recommended) | |
| ### 2. Upload Files | |
| Upload semua files dalam folder ini ke Space repository: | |
| ``` | |
| hf-funcaptcha-deployment/ | |
| ├── Dockerfile # Docker configuration | |
| ├── app.py # Main FastAPI application | |
| ├── requirements.txt # Python dependencies | |
| ├── README.md # Documentation (this file) | |
| ├── data.yaml # Class names untuk default model | |
| ├── best.onnx # ONNX model file (upload manually) | |
| └── test-api.py # Testing script | |
| ``` | |
| ### 3. Setup API Key (CRITICAL!) | |
| 1. Di Space settings, buka tab **"Settings"** | |
| 2. Scroll ke **"Repository secrets"** | |
| 3. Add new secret: | |
| - **Name**: `FUNCAPTCHA_API_KEY` | |
| - **Value**: `your-secure-api-key-here` (generate strong key) | |
| > ⚠️ **PENTING**: Tanpa API key, aplikasi tidak akan start! | |
| ### 4. Upload Model Files | |
| Upload model files ke Space repository: | |
| - `best.onnx` - Main detection model | |
| - `data.yaml` - Class names configuration | |
| - `bestspiral.onnx` (optional) - Spiral galaxy model | |
| - `dataspiral.yaml` (optional) - Spiral galaxy classes | |
| - `best_Upright.onnx` (optional) - Upright detection model | |
| - `data_upright.yaml` (optional) - Upright detection classes | |
| ### 5. Deploy & Test | |
| 1. Space akan auto-deploy setelah files uploaded | |
| 2. Wait untuk build process selesai (~5-10 minutes) | |
| 3. Test endpoint: `https://your-space-url.hf.space/health` | |
| ## 🔑 Authentication | |
| Semua API endpoints require **Bearer token authentication**: | |
| ```bash | |
| # Example request | |
| curl -X POST "https://your-space-url.hf.space/solve" \\ | |
| -H "Authorization: Bearer YOUR_API_KEY" \\ | |
| -H "Content-Type: application/json" \\ | |
| -d '{ | |
| "challenge_type": "pick_the", | |
| "image_b64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", | |
| "target_label": "ice cream" | |
| }' | |
| ``` | |
| ## 📝 API Documentation | |
| ### Endpoints | |
| | Endpoint | Method | Description | Auth Required | | |
| |---|---|---|---| | |
| | `/` | GET | Root info & status | ❌ | | |
| | `/health` | GET | Health check | ❌ | | |
| | `/solve` | POST | Solve FunCaptcha | ✅ | | |
| | `/docs` | GET | Interactive API docs | ❌ | | |
| ### Request Format | |
| ```json | |
| { | |
| "challenge_type": "pick_the", | |
| "image_b64": "data:image/png;base64,iVBORw0KGgo...", | |
| "target_label": "ice cream" | |
| } | |
| ``` | |
| ### Response Format | |
| ```json | |
| { | |
| "status": "success", | |
| "box": [120.5, 80.3, 150.0, 100.0], | |
| "confidence": 0.89, | |
| "processing_time": 0.245, | |
| "message": null | |
| } | |
| ``` | |
| ## 🧪 Testing | |
| ### Local Testing | |
| ```bash | |
| # Install dependencies | |
| pip install -r requirements.txt | |
| # Set API key | |
| export FUNCAPTCHA_API_KEY="your-test-key" | |
| # Run server | |
| python app.py | |
| # Test with provided script | |
| python test-api.py | |
| ``` | |
| ### Production Testing | |
| ```python | |
| import requests | |
| import base64 | |
| # Load test image | |
| with open("test_image.png", "rb") as f: | |
| image_b64 = base64.b64encode(f.read()).decode() | |
| # Make request | |
| response = requests.post( | |
| "https://your-space-url.hf.space/solve", | |
| headers={"Authorization": "Bearer YOUR_API_KEY"}, | |
| json={ | |
| "challenge_type": "pick_the", | |
| "image_b64": f"data:image/png;base64,{image_b64}", | |
| "target_label": "ice cream" | |
| } | |
| ) | |
| print(response.json()) | |
| ``` | |
| ## ⚙️ Configuration | |
| ### Model Configuration | |
| Edit `CONFIGS` in `app.py` untuk custom models: | |
| ```python | |
| CONFIGS = { | |
| 'default': { | |
| 'model_path': 'best.onnx', | |
| 'yaml_path': 'data.yaml', | |
| 'input_size': 640, | |
| 'confidence_threshold': 0.4, | |
| 'nms_threshold': 0.2 | |
| } | |
| # Add more models... | |
| } | |
| ``` | |
| ### Environment Variables | |
| | Variable | Description | Required | | |
| |---|---|---| | |
| | `FUNCAPTCHA_API_KEY` | API key untuk authentication | ✅ | | |
| | `OMP_NUM_THREADS` | CPU threads untuk optimization | ❌ (default: 2) | | |
| | `CACHE_MAX_SIZE` | Maximum cache entries | ❌ (default: 100) | | |
| ## 🔍 Monitoring & Debugging | |
| ### Health Check | |
| ```bash | |
| curl https://your-space-url.hf.space/health | |
| ``` | |
| ### Logs | |
| - Check HF Spaces logs dalam space interface | |
| - Logs include processing times, cache hits, errors | |
| ### Performance Metrics | |
| - **Processing time**: Biasanya < 300ms per request | |
| - **Memory usage**: ~500MB dengan 1 model loaded | |
| - **Cache hit rate**: Displayed in `/health` endpoint | |
| ## 🚨 Troubleshooting | |
| ### Common Issues | |
| 1. **"API key not found"** | |
| - Solution: Set `FUNCAPTCHA_API_KEY` di Space secrets | |
| 2. **"Model file not found"** | |
| - Solution: Upload model files (.onnx, .yaml) ke repository | |
| 3. **"401 Unauthorized"** | |
| - Solution: Check API key dalam request header | |
| 4. **Slow responses** | |
| - Check: Model loading, enable caching | |
| - Monitor: Memory usage dalam Space logs | |
| ### Debug Mode | |
| Untuk debugging, set logging level: | |
| ```python | |
| import logging | |
| logging.basicConfig(level=logging.DEBUG) | |
| ``` | |
| ## 📊 Performance Optimization | |
| - ✅ **Model caching** - Models loaded once, reused | |
| - ✅ **Response caching** - Identical requests cached | |
| - ✅ **CPU optimization** - ONNX dengan CPU-specific settings | |
| - ✅ **Memory efficiency** - Minimal memory footprint | |
| - ✅ **Async operations** - Non-blocking request handling | |
| ## 🔐 Security | |
| - ✅ **API key authentication** via Bearer tokens | |
| - ✅ **CORS protection** configured | |
| - ✅ **Input validation** dengan Pydantic models | |
| - ✅ **Error handling** tanpa expose internal details | |
| ## 📞 Support | |
| - **Issues**: Report dalam repository issues | |
| - **Updates**: Check Space status dan rebuild jika needed | |
| - **Performance**: Monitor via `/health` endpoint | |
| --- | |
| > 🎯 **Ready to deploy?** Upload files, set API key, dan Space siap digunakan! | |
| ## 🌐 Client Integration | |
| Update client untuk menggunakan Space URL: | |
| ```javascript | |
| // funcaptcha-blob-fixed.js | |
| const SOLVER_SERVER_URL = 'https://your-space-url.hf.space/solve'; | |
| const API_KEY = 'your-api-key-here'; | |
| ``` | |