Vision AI reCAPTCHA Solver

</div>

AI powered reCAPTCHA solver for reCAPTCHA v2 and v3 using YOLO based vision models (57k images dataset). The library provides both synchronous and asynchronous APIs, to automate image challenge solving and token extraction.

https://github.com/user-attachments/assets/3d0de5bd-6bbd-4a1a-bb06-fd7efa9d55fd

Key features

Supports reCAPTCHA v2 image challenges (3x3 selection, 3x3 dynamic, 4x4 square) and v3 invisible flows
Synchronous and asynchronous solver APIs with context manager support
Configurable proxy, browser path, timeouts, and detection thresholds
CLI for quick testing and automation
Works in headless mode
Automatic model warmup and background initialization
Automatic model downloads on first run (classification + detection)

How it works

recaptcha-domain-replicator spins up a local HTTPS server and replicates the target reCAPTCHA widget.
A Chromium browser session is launched and the checkbox/challenge is interacted with automatically.
Challenge images are downloaded and analyzed by YOLO models:
- Classification model for 3x3 challenges
- Detection model for 4x4 challenges
The solver clicks the predicted tiles, submits verification, and extracts the token.

RecaptchaDomainReplicator usage

This project uses RecaptchaDomainReplicator (from recaptcha-domain-replicator) to build the local replica page and launch the browser session. It creates a new replicator, starts a local HTTPS server, and returns the browser instance plus a token handle.

Requirements

Python 3.10 or newer
Browser: Chromium based browser (Chrome for Testing, Edge)
For credential proxies: Use Chrome for Testing or Microsoft Edge (Newer versions of Google Chrome doesn't support this)
Admin privileges (optional): Required only for hosts file changes and port forwarding

Installation

pip install vision-ai-recaptcha-solver

From source (recommended for development):

python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"

Quick start (synchronous)

from vision_ai_recaptcha_solver import RecaptchaSolver, SolverConfig

config = SolverConfig(
    timeout=200,
    # Optional: point to a specific Chromium binary
    # browser_path="path/to/chrome.exe",
    # proxy="http://username:password@ip:port",
)

with RecaptchaSolver(config) as solver:
    result = solver.solve(
        website_key="your_site_key",
        website_url="https://example.com/your-page-with-recaptcha",
    )

print(result.token)
print(result.captcha_type.value)
print(result.time_taken)
print(result.attempts)

Invisible reCAPTCHA (v3)

from vision_ai_recaptcha_solver import RecaptchaSolver, SolverConfig

config = SolverConfig(timeout=120)

with RecaptchaSolver(config) as solver:
    result = solver.solve(
        website_key="your_site_key",
        website_url="https://example.com/login",
        is_invisible=True,
        action="login",
        is_enterprise=False,
        api_domain="google.com",
        cookies=None,
        user_agent=None,
    )

print(result.token)

Async usage

import asyncio
from pathlib import Path

from vision_ai_recaptcha_solver import AsyncRecaptchaSolver, SolverConfig

async def main():
    config = SolverConfig(
        timeout=180,
        server_port=8443,
        download_dir=Path("tmp1"),
    )

    async with AsyncRecaptchaSolver(config) as solver:
        result = await solver.solve(
            website_key="your_site_key",
            website_url="https://example.com/your-page-with-recaptcha",
        )
        print(result.token)

asyncio.run(main())

Concurrent async solves

Each solver instance should use a distinct server_port and download_dir to avoid conflicts.

import asyncio
from pathlib import Path

from vision_ai_recaptcha_solver import AsyncRecaptchaSolver, SolverConfig

async def solve_one(name: str, config: SolverConfig):
    async with AsyncRecaptchaSolver(config) as solver:
        result = await solver.solve(
            website_key="your_site_key",
            website_url="https://example.com/your-page-with-recaptcha",
        )
        return name, result

async def main():
    config_a = SolverConfig(server_port=8443, download_dir=Path("tmp-a"))
    config_b = SolverConfig(server_port=8444, download_dir=Path("tmp-b"))

    results = await asyncio.gather(
        solve_one("A", config_a),
        solve_one("B", config_b),
    )

    for name, result in results:
        print(name, result.captcha_type.value, result.time_taken)

asyncio.run(main())

CLI

The package exposes a console script:

vision-ai-recaptcha-solver --help

Solve a captcha:

vision-ai-recaptcha-solver solve \
  --website-key "your_site_key" \
  --website-url "https://example.com/your-page-with-recaptcha" \
  --no-headless \
  --timeout 180 \
  --output json

Solve invisible reCAPTCHA (v3):

vision-ai-recaptcha-solver solve \
  --website-key "your_site_key" \
  --website-url "https://example.com/login" \
  --invisible \
  --action "login"

Run a demo against Google's test page:

vision-ai-recaptcha-solver demo

Configuration reference

SolverConfig controls runtime behavior and validation.

| Option | Default | Description | | --- | --- | --- | | model_path | None | Path to the classification ONNX model. If None, auto downloads from Hugging Face. | | detection_model_path | None | Path to detection model. If None, uses yolo12x.pt. | | download_dir | Path("tmp") | Directory for downloaded images and temp files. | | server_port | 8443 | Local HTTPS port used by the replicator. | | proxy | None | Proxy URL in protocol://[user:pass@]host:port format. | | browser_path | None | Path to Chromium executable. Auto detected if omitted. | | headless | False | Run browser in headless mode. | | timeout | 300.0 | Max seconds to wait for token extraction. | | max_attempts | 12 | Max attempts for solving a challenge. | | human_delay_mean | 0.2 | Mean delay in seconds between interactions. | | human_delay_sigma | 0.1 | Standard deviation for human like delays. | | log_level | "WARNING" | Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL). | | persist_html | False | Persist the generated HTML replicas. | | verbose | False | Enable verbose output. | | conf_threshold | 0.7 | Tile classification confidence threshold. | | min_confidence_threshold | 0.2 | Minimum confidence for top 3 tiles (3x3). | | fourth_cell_threshold | 0.7 | Confidence threshold to include 4th cell. | | detection_conf_threshold | 0.6 | Confidence threshold for 4x4 detection. | | default_timeout | 10.0 | Default timeout for browser operations. | | image_download_retries | 3 | Image download retries. | | image_download_retry_delay | 1.0 | Base delay between retries. | | register_signal_handlers | True | Register SIGINT/SIGTERM handlers for cleanup. | | cleanup_tmp_on_close | True | Delete download_dir when solver closes. |

Solve parameters

Both RecaptchaSolver.solve() and AsyncRecaptchaSolver.solve() support:

website_key: reCAPTCHA site key (required)
website_url: URL containing the challenge (required)
is_invisible: Whether this is invisible/v3 (default False)
action: Action name for invisible reCAPTCHA (optional)
is_enterprise: Whether this is enterprise reCAPTCHA (default False)
api_domain: google.com or recaptcha.net (default google.com)
bypass_domain_check: Skip domain verification (default True)
use_ssl: Use HTTPS for local server (default True)
cookies: Optional list of cookie dictionaries to set before solving
user_agent: Optional custom user agent string

Result object

SolveResult is returned for successful solves:

token: reCAPTCHA response token
cookies: cookies from the browser session
time_taken: wall clock time in seconds
captcha_type: one of dynamic_3x3, selection_3x3, square_4x4, invisible, no_challenge, unknown
attempts: number of solve attempts

Model assets

Classification model: recaptcha_classification_57k.onnx
- Trained on a 57k images dataset.
- Auto downloaded on first use from Hugging Face if not present.
- Override with SolverConfig(model_path=...).
Detection model: yolo12x.pt
- Loaded by `ultral

VisionAIRecaptchaSolver

Install / Use

README