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 python3_capsolver.image_to_text import ImageToText

# 1. Initialize with API Key
solver = ImageToText(api_key="YOUR_API_KEY")

# 2. Solve
result = solver.captcha_handler(
    task_payload={
        "body": "base64_encoded_image_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(
        api_key="YOUR_API_KEY", 
        captcha_type=CaptchaTypeEnm.ReCaptchaV2TaskProxyLess
    )

    # 2. Solve
    result = await solver.aio_captcha_handler(
        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 API_KEY="your_api_key_here"

# 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.

Changelog

See CHANGELOG.md for version history and detailed changes.

How to get API Key to work with the library

1. On the page - https://dashboard.capsolver.com/overview/user-center
2. Find it:

Contacts

If you have any questions, please send a message to the Telegram chat room.

Or email python-captcha@pm.me