🧩 OhMyCaptcha

Self-hostable YesCaptcha-style captcha solver for flow2api and similar integrations
19 task types · reCAPTCHA v2/v3 · hCaptcha · Cloudflare Turnstile · Image Classification

Quick Start • Architecture • Task Types • Deployment • Development

中文说明 • Documentation • Render Guide • Hugging Face Guide

---

✨ 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

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:

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

---

🏗 Architecture

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

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

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

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

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

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) — deploy Qwen3.5-2B locally
• Render deployment
• Hugging Face Spaces deployment
• Full documentation

---

✅ 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

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

---

Star History

---

📄 License

MIT — use freely, modify openly, deploy carefully.

See DISCLAIMER.md for full terms of use and liability limitations.