---
title: OhMyCaptcha API
emoji: 🧩
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
---
<p align="center">
  <img src="https://img.shields.io/badge/OhMyCaptcha-YesCaptcha--style%20API-2F6BFF?style=for-the-badge" alt="OhMyCaptcha">
  <br/>
  <img src="https://img.shields.io/badge/version-3.0-22C55E?style=flat-square" alt="Version">
  <img src="https://img.shields.io/badge/license-MIT-2563EB?style=flat-square" alt="License">
  <img src="https://img.shields.io/badge/task%20types-19-F59E0B?style=flat-square" alt="Task Types">
  <img src="https://img.shields.io/badge/runtime-FastAPI%20%7C%20Playwright%20%7C%20OpenAI--compatible-7C3AED?style=flat-square" alt="Runtime">
  <img src="https://img.shields.io/badge/deploy-Render%20%7C%20Hugging%20Face%20Spaces-0F172A?style=flat-square" alt="Deploy">
  <img src="https://img.shields.io/badge/docs-bilingual-2563EB?style=flat-square" alt="Docs">
</p>

<h1 align="center">🧩 OhMyCaptcha</h1>

<p align="center">
  <strong>Self-hostable YesCaptcha-style captcha solver for <a href="https://github.com/TheSmallHanCat/flow2api">flow2api</a> and similar integrations</strong>
  <br/>
  <em>19 task types · reCAPTCHA v2/v3 · hCaptcha · Cloudflare Turnstile · Image Classification</em>
</p>

<p align="center">
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-architecture">Architecture</a> •
  <a href="#-task-types">Task Types</a> •
  <a href="#-deployment">Deployment</a> •
  <a href="#-development">Development</a>
</p>

<p align="center">
  <a href="README.zh-CN.md">中文说明</a> •
  <a href="https://shenhao-stu.github.io/ohmycaptcha/">Documentation</a> •
  <a href="https://shenhao-stu.github.io/ohmycaptcha/deployment/render/">Render Guide</a> •
  <a href="https://shenhao-stu.github.io/ohmycaptcha/deployment/huggingface/">Hugging Face Guide</a>
</p>

<p align="center">
  <img src="docs/assets/ohmycaptcha-hero.png" alt="OhMyCaptcha" width="680">
</p>

---

## ✨ What Is This?

**OhMyCaptcha** is a self-hosted captcha-solving service exposing a **YesCaptcha-style async API** with **19 supported task types**. Designed as a third-party captcha solver for **flow2api** and systems that expect `createTask` / `getTaskResult` semantics.

| Capability | Details |
|-----------|---------|
| **Browser automation** | Playwright + Chromium for reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile |
| **Image recognition** | Local multimodal model (Qwen3.5-2B via SGLang) for image captcha analysis |
| **Image classification** | Local vision model for HCaptcha, reCAPTCHA v2, FunCaptcha, AWS grid classification |
| **API compatibility** | Full YesCaptcha `createTask`/`getTaskResult`/`getBalance` protocol |
| **Deployment** | Local, Render, Hugging Face Spaces with Docker support |

---

## 📦 Quick Start

```bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
playwright install --with-deps chromium

# Local model (self-hosted via SGLang)
export LOCAL_BASE_URL="http://localhost:30000/v1"
export LOCAL_MODEL="Qwen/Qwen3.5-2B"

# Cloud model (remote API)
export CLOUD_BASE_URL="https://your-openai-compatible-endpoint/v1"
export CLOUD_API_KEY="your-api-key"
export CLOUD_MODEL="gpt-5.4"

export CLIENT_KEY="your-client-key"
python main.py
```

Verify with:

```bash
curl http://localhost:8000/api/v1/health
```

---

## 🏗 Architecture

<p align="center">
  <img src="docs/assets/ohmycaptcha-diagram.png" alt="OhMyCaptcha architecture" width="560">
</p>

**Core components:**

- **FastAPI** — HTTP API with YesCaptcha protocol
- **TaskManager** — async in-memory task queue with 10-min TTL
- **RecaptchaV3Solver** — Playwright-based reCAPTCHA v3/Enterprise token generation
- **RecaptchaV2Solver** — Playwright-based reCAPTCHA v2 checkbox solving
- **HCaptchaSolver** — Playwright-based hCaptcha solving
- **TurnstileSolver** — Playwright-based Cloudflare Turnstile solving
- **CaptchaRecognizer** — Argus-inspired multimodal image analysis
- **ClassificationSolver** — Vision model-based image classification

---

## 🧠 Task Types

### Browser-based solving (12 types)

| Category | Task Types | Solution Field |
|----------|-----------|----------------|
| reCAPTCHA v3 | `RecaptchaV3TaskProxyless`, `RecaptchaV3TaskProxylessM1`, `RecaptchaV3TaskProxylessM1S7`, `RecaptchaV3TaskProxylessM1S9` | `gRecaptchaResponse` |
| reCAPTCHA v3 Enterprise | `RecaptchaV3EnterpriseTask`, `RecaptchaV3EnterpriseTaskM1` | `gRecaptchaResponse` |
| reCAPTCHA v2 | `NoCaptchaTaskProxyless`, `RecaptchaV2TaskProxyless`, `RecaptchaV2EnterpriseTaskProxyless` | `gRecaptchaResponse` |
| hCaptcha | `HCaptchaTaskProxyless` | `gRecaptchaResponse` |
| Cloudflare Turnstile | `TurnstileTaskProxyless`, `TurnstileTaskProxylessM1` | `token` |

### Image recognition (3 types)

| Task Type | Solution Field |
|-----------|----------------|
| `ImageToTextTask` | `text` (structured JSON) |
| `ImageToTextTaskMuggle` | `text` |
| `ImageToTextTaskM1` | `text` |

### Image classification (4 types)

| Task Type | Solution Field |
|-----------|----------------|
| `HCaptchaClassification` | `objects` / `answer` |
| `ReCaptchaV2Classification` | `objects` |
| `FunCaptchaClassification` | `objects` |
| `AwsClassification` | `objects` |

---

## 🔌 API Surface

| Endpoint | Purpose |
|----------|---------|
| `POST /createTask` | Create an async captcha task |
| `POST /getTaskResult` | Poll task execution result |
| `POST /getBalance` | Return compatibility balance |
| `GET /api/v1/health` | Health and service status |

### Example: reCAPTCHA v3

```bash
curl -X POST http://localhost:8000/createTask \
  -H "Content-Type: application/json" \
  -d '{
    "clientKey": "your-client-key",
    "task": {
      "type": "RecaptchaV3TaskProxyless",
      "websiteURL": "https://antcpt.com/score_detector/",
      "websiteKey": "6LcR_okUAAAAAPYrPe-HK_0RULO1aZM15ENyM-Mf",
      "pageAction": "homepage"
    }
  }'
```

### Example: hCaptcha

```bash
curl -X POST http://localhost:8000/createTask \
  -H "Content-Type: application/json" \
  -d '{
    "clientKey": "your-client-key",
    "task": {
      "type": "HCaptchaTaskProxyless",
      "websiteURL": "https://example.com",
      "websiteKey": "hcaptcha-site-key"
    }
  }'
```

### Example: Cloudflare Turnstile

```bash
curl -X POST http://localhost:8000/createTask \
  -H "Content-Type: application/json" \
  -d '{
    "clientKey": "your-client-key",
    "task": {
      "type": "TurnstileTaskProxyless",
      "websiteURL": "https://example.com",
      "websiteKey": "turnstile-site-key"
    }
  }'
```

### Example: Image classification

```bash
curl -X POST http://localhost:8000/createTask \
  -H "Content-Type: application/json" \
  -d '{
    "clientKey": "your-client-key",
    "task": {
      "type": "ReCaptchaV2Classification",
      "image": "<base64-encoded-image>",
      "question": "Select all images with traffic lights"
    }
  }'
```

### Poll result

```bash
curl -X POST http://localhost:8000/getTaskResult \
  -H "Content-Type: application/json" \
  -d '{"clientKey": "your-client-key", "taskId": "uuid-from-createTask"}'
```

---

## ⚙️ Configuration

### Model backends

OhMyCaptcha uses two model backends — a **local model** for image tasks and a **cloud model** for complex reasoning:

| Variable | Description | Default |
|----------|-------------|---------|
| `LOCAL_BASE_URL` | Local inference server (SGLang/vLLM) | `http://localhost:30000/v1` |
| `LOCAL_API_KEY` | Local server API key | `EMPTY` |
| `LOCAL_MODEL` | Local model name | `Qwen/Qwen3.5-2B` |
| `CLOUD_BASE_URL` | Cloud API base URL | External endpoint |
| `CLOUD_API_KEY` | Cloud API key | unset |
| `CLOUD_MODEL` | Cloud model name | `gpt-5.4` |

### General

| Variable | Description | Default |
|----------|-------------|---------|
| `CLIENT_KEY` | Client authentication key | unset |
| `CAPTCHA_RETRIES` | Retry count | `3` |
| `CAPTCHA_TIMEOUT` | Model timeout (seconds) | `30` |
| `BROWSER_HEADLESS` | Headless Chromium | `true` |
| `BROWSER_TIMEOUT` | Page load timeout (seconds) | `30` |
| `SERVER_HOST` | Bind host | `0.0.0.0` |
| `SERVER_PORT` | Bind port | `8000` |

> Legacy vars (`CAPTCHA_BASE_URL`, `CAPTCHA_API_KEY`, `CAPTCHA_MODEL`, `CAPTCHA_MULTIMODAL_MODEL`) are supported as fallbacks.

---

## 🚀 Deployment

- [Local model (SGLang)](https://shenhao-stu.github.io/ohmycaptcha/deployment/local-model/) — deploy Qwen3.5-2B locally
- [Render deployment](https://shenhao-stu.github.io/ohmycaptcha/deployment/render/)
- [Hugging Face Spaces deployment](https://shenhao-stu.github.io/ohmycaptcha/deployment/huggingface/)
- [Full documentation](https://shenhao-stu.github.io/ohmycaptcha/)

---

## ✅ Test Target

This service is validated against the public reCAPTCHA v3 score detector:

- URL: `https://antcpt.com/score_detector/`
- Site key: `6LcR_okUAAAAAPYrPe-HK_0RULO1aZM15ENyM-Mf`

---

## ⚠️ Limitations

- Tasks are stored **in memory** with a 10-minute TTL
- `minScore` is accepted for compatibility but not enforced
- Browser-based solving depends on environment, IP reputation, and target-site behavior
- Image classification quality depends on the vision model used
- Not all commercial captcha-service features are replicated

---

## 📢 Disclaimer

> **This project is intended for legitimate research, security testing, and educational purposes only.**

- OhMyCaptcha is a self-hostable tool. You are solely responsible for how you deploy and use it.
- CAPTCHA systems exist to protect services from abuse. **Do not use this tool to bypass CAPTCHAs on websites or services without explicit permission from the site owner.**
- Unauthorized automated access to third-party services may violate their Terms of Service, and may be illegal under applicable laws (e.g., the Computer Fraud and Abuse Act, GDPR, or equivalent legislation in your jurisdiction).
- The authors and contributors of this project **accept no liability** for any misuse, legal consequences, or damages arising from the use of this software.
- By using this software, you agree that you are solely responsible for ensuring your usage complies with all relevant laws and terms of service.

---

## 🔧 Development

```bash
pytest tests/
npx pyright
python -m mkdocs build --strict
```

---

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=shenhao-stu/ohmycaptcha&type=Date)](https://www.star-history.com/#shenhao-stu/ohmycaptcha&Date)

---

## 📄 License

[MIT](LICENSE) — use freely, modify openly, deploy carefully.

See [DISCLAIMER.md](DISCLAIMER.md) for full terms of use and liability limitations.