# 🛡️ CaptchaFlow API

<div align="center">

**Universal AI-Powered Captcha Solving API**

19 Task Types · 7 Categories · Universal Captcha Protocol

[![API Status](https://img.shields.io/badge/status-live-brightgreen)](https://captcha.dataleads.pro/v1/api/v1/health)
[![Protocol](https://img.shields.io/badge/protocol-leading captcha providers%20compatible-blue)]
[![Task Types](https://img.shields.io/badge/task%20types-19-orange)](#supported-task-types)
[![AI Backend](https://img.shields.io/badge/AI-Advanced%20Vision%20Engine-purple)]

</div>

---

## 📖 Overview

CaptchaFlow API is a production-grade captcha-solving service supporting **19 task types** across **7 captcha categories**. It combines a **AI vision engine vision backend** with **Playwright + Chromium** browser automation to deliver reliable, automated captcha solving for web scraping, testing, and automation workflows.

The API follows the widely-adopted **industry-standard captcha protocol**, making it a **drop-in replacement** for existing integrations. If your code already works with leading captcha providers or leading captcha providers, switch by changing the base URL and client key — no code changes required.

## 🚀 Quick Start

### Base Configuration

```yaml
Base URL:   https://captcha.dataleads.pro/v1
Client Key: captcha_solver_key_2026
Auth:       clientKey in JSON body
Protocol:   Industry-standard captcha protocol
```

### Solve Your First Captcha (cURL)

```bash
# 1. Create a task
curl -X POST https://captcha.dataleads.pro/v1/createTask \
  -H "Content-Type: application/json" \
  -d '{
    "clientKey": "captcha_solver_key_2026",
    "task": {
      "type": "RecaptchaV2TaskProxyless",
      "websiteURL": "https://example.com",
      "websiteKey": "6Le-wvkSVVABBPB0JGLdnLBwZdMwQXa5JbjJWkA"
    }
  }'

# 2. Poll for the result
curl -X POST https://captcha.dataleads.pro/v1/getTaskResult \
  -H "Content-Type: application/json" \
  -d '{
    "clientKey": "captcha_solver_key_2026",
    "taskId": "YOUR_TASK_ID"
  }'
```

### Python Example

```python
import requests

BASE_URL = "https://captcha.dataleads.pro/v1"
CLIENT_KEY = "captcha_solver_key_2026"

# Create task
resp = requests.post(f"{BASE_URL}/createTask", json={
    "clientKey": CLIENT_KEY,
    "task": {
        "type": "RecaptchaV2TaskProxyless",
        "websiteURL": "https://example.com",
        "websiteKey": "6Le-wvkSVVABBPB0JGLdnLBwZdMwQXa5JbjJWkA"
    }
})
task_id = resp.json()["taskId"]

# Poll for result
import time
while True:
    result = requests.post(f"{BASE_URL}/getTaskResult", json={
        "clientKey": CLIENT_KEY,
        "taskId": task_id
    }).json()
    if result["status"] in ("ready", "failed"):
        print(result)
        break
    time.sleep(5)
```

## 📋 API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/createTask` | POST | Submit a captcha-solving task (async, returns `taskId`) |
| `/getTaskResult` | POST | Poll for task result (returns `processing`/`ready`/`failed`) |
| `/getBalance` | POST | Check account balance (returns `99999.0`) |
| `/api/v1/health` | GET | Health check + supported task types |
| `/` | GET | Service info |

## 🧩 Supported Task Types (19)

### Browser-Based Tasks (12)

Powered by **Playwright + Chromium** browser automation.

| Task Type | Category | Solution Field |
|-----------|----------|----------------|
| `RecaptchaV2TaskProxyless` | reCAPTCHA v2 | `gRecaptchaResponse` |
| `RecaptchaV2EnterpriseTaskProxyless` | reCAPTCHA v2 Enterprise | `gRecaptchaResponse` |
| `NoCaptchaTaskProxyless` | reCAPTCHA v2 (legacy) | `gRecaptchaResponse` |
| `RecaptchaV3TaskProxyless` | reCAPTCHA v3 | `gRecaptchaResponse` |
| `RecaptchaV3TaskProxylessM1` | reCAPTCHA v3 (M1) | `gRecaptchaResponse` |
| `RecaptchaV3TaskProxylessM1S7` | reCAPTCHA v3 (M1, score 0.7) | `gRecaptchaResponse` |
| `RecaptchaV3TaskProxylessM1S9` | reCAPTCHA v3 (M1, score 0.9) | `gRecaptchaResponse` |
| `RecaptchaV3EnterpriseTask` | reCAPTCHA v3 Enterprise | `gRecaptchaResponse` |
| `RecaptchaV3EnterpriseTaskM1` | reCAPTCHA v3 Enterprise (M1) | `gRecaptchaResponse` |
| `HCaptchaTaskProxyless` | hCaptcha | `gRecaptchaResponse` |
| `TurnstileTaskProxyless` | Cloudflare Turnstile | `token` |
| `TurnstileTaskProxylessM1` | Cloudflare Turnstile (M1) | `token` |

### Image Text Tasks (3)

Powered by an **advanced AI vision engine**.

| Task Type | Description | Solution Field |
|-----------|-------------|----------------|
| `ImageToTextTask` | Standard image captcha | `text` |
| `ImageToTextTaskMuggle` | Muggle-style image captcha | `text` |
| `ImageToTextTaskM1` | M1 model image captcha | `text` |

### Classification Tasks (4)

Powered by an **advanced AI vision engine**.

| Task Type | Description | Solution Field |
|-----------|-------------|----------------|
| `HCaptchaClassification` | hCaptcha image classification | `objects` / `answer` |
| `ReCaptchaV2Classification` | reCAPTCHA v2 image classification | `objects` / `answer` |
| `FunCaptchaClassification` | FunCaptcha image classification | `objects` / `answer` |
| `AwsClassification` | AWS WAF captcha classification | `objects` / `answer` |

## 📝 Request/Response Examples

### createTask

**Image captcha:**
```json
{
  "clientKey": "captcha_solver_key_2026",
  "task": {
    "type": "ImageToTextTask",
    "body": "<base64_encoded_image>"
  }
}
```

**Browser captcha (reCAPTCHA v2):**
```json
{
  "clientKey": "captcha_solver_key_2026",
  "task": {
    "type": "RecaptchaV2TaskProxyless",
    "websiteURL": "https://example.com",
    "websiteKey": "6Le-wvkSVVABBPB0JGLdnLBwZdMwQXa5JbjJWkA"
  }
}
```

**Response:**
```json
{
  "errorId": 0,
  "taskId": "550e8400-e29b-41d4-a716-446655440000"
}
```

### getTaskResult

**Processing:**
```json
{
  "errorId": 0,
  "status": "processing"
}
```

**Ready (reCAPTCHA/hCaptcha):**
```json
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "03AGdBq25..."
  }
}
```

**Ready (Turnstile):**
```json
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "0.eYEMe..."
  }
}
```

**Ready (ImageToText):**
```json
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "text": "{\"captcha_type\": \"text\", \"result\": \"ABCD\"}"
  }
}
```

**Failed:**
```json
{
  "errorId": 1,
  "errorCode": "ERROR_CAPTCHA_UNSOLVABLE",
  "errorDescription": "Unable to solve the captcha"
}
```

### getBalance

```json
// Request
{
  "clientKey": "captcha_solver_key_2026"
}

// Response
{
  "errorId": 0,
  "balance": 99999.0
}
```

## ⚠️ Error Codes

| Error ID | Error Code | Description |
|----------|-----------|-------------|
| 0 | — | No error (success) |
| 1 | `ERROR_KEY_DOES_NOT_EXIST` | Invalid clientKey |
| 1 | `ERROR_WRONG_GOOGLEKEY` | Invalid websiteKey for reCAPTCHA tasks |
| 1 | `ERROR_BAD_TOKEN` | Invalid or expired taskId |
| 1 | `ERROR_CAPTCHA_UNSOLVABLE` | Captcha could not be solved |
| 1 | `ERROR_NO_SUCH_METHOD` | Unsupported task type |
| 1 | `ERROR_TASK_NOT_FOUND` | taskId does not exist |
| 1 | `ERROR_PROXY_CONNECT_REFUSED` | Proxy connection refused (not used in proxyless mode) |

## 💻 Code Examples

Complete client examples are available in the `examples/` directory:

| Language | File | Dependencies |
|----------|------|--------------|
| **Python** | `examples/python.py` | None (stdlib only) |
| **JavaScript** | `examples/javascript.js` | Node.js 18+ (built-in fetch) |
| **PHP** | `examples/php.php` | PHP 7.4+ with cURL |
| **Go** | `examples/go.go` | Go 1.21+ |
| **cURL** | `examples/curl.sh` | curl, bash, python3 |

## 📦 Additional Resources

| Resource | File | Description |
|----------|------|-------------|
| **OpenAPI Spec** | `openapi.json` | Full OpenAPI 3.0 specification |
| **HTML Docs** | `index.html` | Interactive documentation page |
| **Postman Collection** | `postman_collection.json` | Pre-configured Postman collection |
| **Marketplace Listings** | `marketplace_listings.md` | Ready-to-use marketplace copy |

## 🏗️ Architecture

```
┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Client     │────▶│  CaptchaFlow API │────▶│  Task Queue      │
│  (any lang)  │◀────│  (FastAPI)       │◀────│  (async worker)  │
└──────────────┘     └──────────────────┘     └────────┬────────┘
                                                       │
                          ┌────────────────────────────┼────────────────────┐
                          ▼                            ▼                    ▼
                   ┌─────────────┐         ┌─────────────────┐    ┌──────────────┐
                   │ AI vision engine │         │   Playwright +   │    │  Result      │
                   │ Engine       │         │   Chromium       │    │  Storage     │
                   │ (vision)     │         │   (browser)      │    │              │
                   └─────────────┘         └─────────────────┘    └──────────────┘
```

### Technology Stack

- **API Framework**: FastAPI (Python)
- **Vision Backend**: advanced AI vision engine
- **Browser Automation**: Playwright + Chromium
- **Protocol**: Industry-standard captcha protocol JSON REST
- **Processing**: Asynchronous task queue

## 🔄 Migrating from other captcha providers

CaptchaFlow API is a drop-in replacement. To migrate:

1. Change your base URL to `https://captcha.dataleads.pro/v1`
2. Set your `clientKey` to `captcha_solver_key_2026`
3. Keep all your existing task types and parameters

No other code changes are needed. The `createTask`, `getTaskResult`, and `getBalance` endpoints work identically.

## 📊 Workflow

```
createTask ──▶ taskId ──▶ getTaskResult (poll) ──▶ status: processing
                                                         │
                                                    (retry every 5s)
                                                         │
                                                         ▼
                                              status: ready / failed
                                                         │
                                              ┌──────────┴──────────┐
                                              ▼                     ▼
                                        solution              errorCode
                                        (token/text)         + errorDescription
```

## 📄 License

This documentation and code examples are provided as-is for integration purposes.

---

<div align="center">

**CaptchaFlow API** — Built for developers who need reliable captcha solving at scale.

[Health Check](https://captcha.dataleads.pro/v1/api/v1/health) · [Service Info](https://captcha.dataleads.pro/v1/) · [Documentation](./index.html)

</div>