python3-capsolver

Python 3 library for Capsolver service API. Tested on UNIX based OS.

The library is intended for software developers and is used to work with the Capsolver service API.

Features

Modern Tooling: Uses uv for fast, reliable dependency management and environment isolation.
Sync & Async Support: Full support for both synchronous (requests) and asynchronous (aiohttp) operations.
Type Safety: Enums for captcha types and response statuses.
Resilience: Built-in retries using tenacity.
Performance: High-speed JSON serialization with msgspec.
Coverage: Supports ReCaptcha (V2/V3), Cloudflare, DataDome, GeeTest, MtCaptcha, AWS WAF, Yandex, and ImageToText.

How to install?

We recommend using the latest version of Python. python3-capsolver supports Python 3.8+.

Development (using uv)

This project uses uv for fast, reliable dependency management.

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
Install project dependencies
uv sync --all-groups

Production (pip)

pip install python3-capsolver

How to use?

Detailed documentation is available on the website.

Quick Start

Synchronous Example (ImageToText)

from python3capsolver.imageto_text import ImageToText
1. Initialize with API Key
solver = ImageToText(apikey="YOURAPI_KEY")
2. Solve
result = solver.captcha_handler(
    task_payload={
        "body": "base64encodedimage_string"
    }
)
3. Check result
if result["errorId"] == 0:
    print("Solution:", result["solution"])
else:
    print("Error:", result["errorCode"])

Asynchronous Example (ReCaptcha)

import asyncio
from python3_capsolver.recaptcha import ReCaptcha
from python3_capsolver.core.enum import CaptchaTypeEnm
async def main():     # 1. Initialize     solver = ReCaptcha(         apikey="YOURAPI_KEY",          captcha_type=CaptchaTypeEnm.ReCaptchaV2TaskProxyLess     )
# 2. Solve     result = await solver.aiocaptchahandler(         task_payload={             "websiteURL": "https://example.com",             "websiteKey": "SITE_KEY"         }     )          print(result)
if name == "main":     asyncio.run(main())

Supported Captcha Types

ReCaptcha: V2 (Task/Enterprise), V3 (Task/Enterprise)
HCaptcha: Task, Enterprise
Cloudflare: Turnstile
GeeTest: V3, V4
DataDome: Slider
MtCaptcha
AWS WAF
Yandex SmartCaptcha
ImageToText: General image CAPTCHAs

Documentation & Context (For LLMs)

Project Structure: See AGENTS.md in root and subdirectories for internal architecture.
Entry Points: src/python3_capsolver/*.py contains service-specific classes (e.g., ReCaptcha, HCaptcha).
Core Logic: src/python3_capsolver/core/base.py handles the API communication loop.
Enums: Use python3_capsolver.core.enum for type-safe parameters.

How to test?

The project uses uv for testing and development tasks.

# 1. Set API_KEY in your environment (get this value from your account)
export APIKEY="yourapikeyhere"
2. Run tests (uses uv internally)
make tests
Other useful make targets:
make install     # Install dependencies with uv sync
make lint        # Run linting checks
make build       # Build the package
make doc         # Generate documentation

All make commands automatically use uv to run commands in the isolated environment.