CapSkip Python SDK

Official Python client for the CapSkip local captcha solver.

CapSkip runs on your machine and exposes a standard captcha-solver HTTP API (the familiar in.php / res.php endpoints). This SDK wraps that API with clean, familiar method names, so you can solve captchas locally — no per-solve API fees beyond your CapSkip license.

Quick start (5 minutes)

1. Install CapSkip

Download and run the CapSkip desktop app from capskip.com. Leave it running in the background.

In CapSkip settings, note:

• API port (default: 8080)
• API key (optional — if validation is disabled, any string works)

2. Install the SDK

pip install capskip

Or from source:

git clone https://github.com/capskip/capskip-python.git
cd capskip-python
pip install -e .

3. Solve your first captcha

from capskip import CapSkip

solver = CapSkip(host="127.0.0.1", port=8080)

result = solver.recaptcha(
    sitekey="YOUR_SITEKEY",
    url="https://example.com/page-with-recaptcha",
)

print(result["code"])  # g-recaptcha-response token

Prerequisite: CapSkip must be running before you call the SDK. If you see a connection error, see Troubleshooting.

Supported captcha types

Documentation

Configuration

from capskip import CapSkip

solver = CapSkip(
    apiKey="capskip",        # your CapSkip API key (or any string if validation is off)
    host="127.0.0.1",        # CapSkip host
    port=8080,               # CapSkip port from app settings
    defaultTimeout=120,      # seconds — image captcha polling timeout
    recaptchaTimeout=300,    # seconds — reCAPTCHA / Turnstile / GeeTest polling timeout
    pollingInterval=5,       # max seconds between res.php polls (starts at 0.25s, backs off to this)
)

Use environment variables in production:

# Linux / macOS
export CAPSKIP_API_KEY="your-key"
export CAPSKIP_HOST="127.0.0.1"
export CAPSKIP_PORT="8080"

# Windows PowerShell
$env:CAPSKIP_API_KEY = "your-key"
$env:CAPSKIP_HOST = "127.0.0.1"
$env:CAPSKIP_PORT = "8080"

import os
from capskip import CapSkip

solver = CapSkip(
    apiKey=os.getenv("CAPSKIP_API_KEY", "capskip"),
    host=os.getenv("CAPSKIP_HOST", "127.0.0.1"),
    port=int(os.getenv("CAPSKIP_PORT", "8080")),
)

Usage examples

Image captcha

result = solver.normal("captcha.png")
result = solver.normal("https://example.com/captcha.jpg")
result = solver.normal("data:image/png;base64,iVBORw0KGgo...")
print(result["code"])

reCAPTCHA v2 / v3

# reCAPTCHA v2
result = solver.recaptcha(sitekey="...", url="https://example.com")

# reCAPTCHA v3
result = solver.recaptcha(
    sitekey="...",
    url="https://example.com",
    version="v3",
    action="submit",
    score=0.7,
)

Cloudflare Turnstile

result = solver.turnstile(
    sitekey="0x4AAAAAAA...",
    url="https://example.com",
)

GeeTest v3

gt is static per site, but challenge is single-use and expires in about a minute — fetch a fresh pair right before solving.

result = solver.geetest(
    gt="81388ea1fc187e0c335c0a8907ff2625",
    challenge="7cf6a8b1a2c34d5e6f7089abcdef0123",
    url="https://example.com/login",
)

# Post these back exactly as the site's own front-end would
result["challenge"], result["validate"], result["seccode"]

With a proxy (reCAPTCHA, Turnstile & GeeTest only)

# Proxy is not supported for image captcha
result = solver.recaptcha(
    sitekey="...",
    url="https://example.com",
    proxy={"type": "HTTPS", "uri": "user:pass@1.2.3.4:3128"},
)
result = solver.turnstile(
    sitekey="...",
    url="https://example.com",
    proxy={"type": "HTTP", "uri": "1.2.3.4:3128"},
)

Async (parallel solving)

import asyncio
from capskip import AsyncCapSkip

async def main():
    solver = AsyncCapSkip()
    r1, r2 = await asyncio.gather(
        solver.recaptcha(sitekey="...", url="https://a.com"),
        solver.turnstile(sitekey="...", url="https://b.com"),
    )
    print(r1["code"], r2["code"])

asyncio.run(main())

More examples: examples/

Return value

Every solve method returns:

{
    "captchaId": "12345",   # internal ID from CapSkip
    "code": "TOKEN_OR_TEXT" # solution — text for image, token for reCAPTCHA/Turnstile
    "userAgent": "..."      # Turnstile only — use when submitting challenge-page tokens
}

GeeTest additionally expands its answer into challenge, validate, and seccode, while code keeps the raw JSON string.

Error handling

from capskip import CapSkip, ValidationException, NetworkException, ApiException, TimeoutException

try:
    result = solver.recaptcha(sitekey="...", url="...")
except ValidationException:
    pass  # invalid parameters
except NetworkException:
    pass  # CapSkip not running, or captcha not ready (manual polling)
except ApiException:
    pass  # API returned an error code
except TimeoutException:
    pass  # polling timeout exceeded

Development

git clone https://github.com/capskip/capskip-python.git
cd capskip-python
python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux / macOS
source .venv/bin/activate

pip install -e ".[dev]"
pytest

See CONTRIBUTING.md for the full development workflow.

Links

• CapSkip website
• CapSkip API docs
• Report an issue
• PyPI package

License

MIT — see LICENSE.