# Python SDK

Official Python SDK for CaptchaSolv. Async support, automatic polling, and type hints included.

pip install captchasolv
# For async: pip install captchasolv[async]

# Quick Start

from captchasolv import CaptchaSolv

solver = CaptchaSolv("YOUR_API_KEY")
result = solver.turnstile(
    website_url="https://example.com",
    website_key="0x4AAAAAAABS7vwvV6VFfMcD"
)
print(result.solution.token)

import asyncio
from captchasolv import AsyncCaptchaSolv

async def main():
    async with AsyncCaptchaSolv("YOUR_API_KEY") as solver:
        result = await solver.turnstile(
            website_url="https://example.com",
            website_key="0x4AAAAAAABS7vwvV6VFfMcD"
        )
        print(result.solution.token)

asyncio.run(main())

# Methods

# Cloudflare Turnstile

result = solver.turnstile(
    website_url="https://example.com",
    website_key="0x4AAAAAAABS7vwvV6VFfMcD",
    proxy="http://user:pass@ip:port",  # optional
    user_agent="Mozilla/5.0 ..."       # optional
)

# reCAPTCHA v3

result = solver.recaptcha_v3(
    website_url="https://example.com",
    website_key="6Le-xxxxx",
    page_action="login",               # optional
)

# GeeTest v4

result = solver.geetest_v4(
    website_url="https://example.com",
    website_key="captcha_id_here",
)

# Akamai

result = solver.akamai(
    website_url="https://example.com",
    akamai_script="https://example.com/akam/13/xxxxx",
    data={"_abck": "...", "bm_sz": "..."},  # optional
)
print(result.solution.cookies)

# Kasada

result = solver.kasada(
    website_url="https://example.com",
    pjs="https://example.com/{uuid1}/{uuid2}/p.js",
    v="i-1.18.2",  # optional
)
print(result.solution.headers)

# DataDome Tags

result = solver.datadome_tags(
    website_url="https://example.com",
    website_key="DATADOME_KEY",  # optional
)
print(result.solution.cookies)

# AWS WAF

result = solver.aws_waf(
    website_url="https://example.com",
    aws_key="AWS_KEY",  # optional
)

All methods accept optional proxy and user_agent parameters.

# Generic Solve

from captchasolv import TaskType

result = solver.solve(
    task_type=TaskType.TURNSTILE,
    website_url="https://example.com",
    website_key="0x4AAAAAAABS7vwvV6VFfMcD",
)

# Polling Mode

task_id = solver.create_task(
    task_type=TaskType.TURNSTILE,
    website_url="https://example.com",
    website_key="0x4AAAAAAABS7vwvV6VFfMcD"
)
result = solver.wait_for_result(task_id, timeout=120)

# Balance

balance = solver.get_balance()

# Error Handling

from captchasolv import (
    CaptchaSolvError,
    InvalidKeyError,
    LimitExceededError,
    CaptchaUnsolvableError,
    TaskNotFoundError,
)

try:
    result = solver.turnstile(...)
except InvalidKeyError:
    print("Invalid API key")
except LimitExceededError:
    print("Balance exhausted")
except CaptchaUnsolvableError:
    print("Failed — retry")
except CaptchaSolvError as e:
    print(f"[{e.error_code}]: {e.error_description}")

# Configuration

solver = CaptchaSolv(
    api_key="YOUR_API_KEY",
    base_url="https://v1.captchasolv.com",
    timeout=130.0,
    poll_interval=3.0,
)

# Response Object

result.status          # "ready" or "processing"
result.is_ready        # True if solved
result.cost            # Cost string
result.solution.token       # Token
result.solution.user_agent  # User agent used
result.solution.cookies     # Cookies dict (Akamai, DataDome)
result.solution.headers     # Headers dict (Kasada)
result.solution.raw         # Raw response dict

# Links

PyPI
GitHub