README.md

---
title: GeeTest4 Solver API
emoji: 🔐
colorFrom: blue
colorTo: purple
sdk: docker
sdk_version: 5.43.1
app_file: hf-geetest4-app.py
pinned: false
license: mit
---

# GeeTest4 Solver API

Pure FastAPI service for solving GeeTest4 captchas. **100% API endpoint** without any UI dependencies.

## 🚀 Features

- **Pure FastAPI**: No Gradio, no UI, just API endpoints
- **ONNX Model**: AI-powered object detection
- **CV Fallback**: Computer Vision fallback for reliability
- **API Key Authentication**: Secure access control
- **Hidden Service**: Root endpoint returns 404 for security

## 📡 API Endpoints

### POST `/api/predict`
Main endpoint for solving GeeTest4 captchas.

**Request:**
```json
{
  "data": ["base64_image_data", "API_KEY"]
}
```

**Response:**
```json
{
  "data": ["✅ Success! Target at x=200 (Model: CV)", 200, 0.75]
}
```

### GET `/health`
Health check endpoint.

**Response:**
```json
{
  "status": "healthy",
  "model_loaded": true
}
```

### GET `/`
Returns 404 (hidden service).

## 🔧 Configuration

- **API Key**: Set via `GEETEST4_API_KEY` environment variable (default: `ADMINCKV005`)
- **Port**: Set via `PORT` environment variable (default: `7860`)

## 🐳 Docker Deployment

This Space uses Docker for deployment:

```dockerfile
FROM python:3.10-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 7860
CMD ["python", "app.py"]
```

## 📦 Dependencies

- `fastapi==0.104.1`
- `uvicorn[standard]==0.24.0`
- `pydantic==2.5.0`
- `numpy==1.24.3`
- `opencv-python==4.8.1.78`
- `Pillow==10.1.0`
- `PyYAML==6.0.1`
- `onnxruntime-cpu==1.15.1`

## 🔒 Security

- API key authentication required
- No UI exposed
- Root endpoint hidden (404)
- Non-root user in Docker container

## 🎯 Usage Example

```bash
curl -X POST https://your-space-name.hf.space/api/predict \
  -H "Content-Type: application/json" \
  -d '{"data": ["base64_image", "ADMINCKV005"]}'
```

## 📊 Performance

- **Startup Time**: ~10-15 seconds
- **Response Time**: ~100-500ms per request
- **Memory Usage**: ~200-300MB
- **CPU**: Optimized for Hugging Face CPU Basic

## 🛠️ Development

For local development:

```bash
pip install -r requirements.txt
python app.py
```

Then test with:
```bash
curl -X POST http://localhost:7860/api/predict \
  -H "Content-Type: application/json" \
  -d '{"data": ["test", "ADMINCKV005"]}'
```