README.md

---

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';

```