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.
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)
pip install capskipOr from source:
git clone https://github.com/capskip/capskip-python.git
cd capskip-python
pip install -e .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 tokenPrerequisite: CapSkip must be running before you call the SDK. If you see a connection error, see Troubleshooting.
| Type | SDK method |
|---|---|
| Image CAPTCHA (distorted text) | solver.normal(file) |
| reCAPTCHA v2 (checkbox) | solver.recaptcha(sitekey, url) |
| reCAPTCHA v2 Invisible | solver.recaptcha(..., invisible=1) |
| reCAPTCHA v2 Enterprise | solver.recaptcha(..., enterprise=1) |
| reCAPTCHA v3 | solver.recaptcha(..., version="v3") |
| reCAPTCHA v3 Enterprise | solver.recaptcha(..., version="v3", enterprise=1) |
| Cloudflare Turnstile (widget) | solver.turnstile(sitekey, url) |
| Cloudflare Turnstile (challenge page) | solver.turnstile(..., data=..., pagedata=...) |
| GeeTest v3 (slide) | solver.geetest(gt, challenge, url) |
| Guide | Description |
|---|---|
| Tutorial | Complete walkthrough of every captcha type, sync and async |
| Getting Started | Full setup: CapSkip app, SDK install, first script |
| API Reference | All classes, methods, parameters, and return values |
| Examples | Ready-to-run scripts for every captcha type |
| Troubleshooting | Connection errors, timeouts, proxy issues |
| Contributing | Development setup, tests, pull requests |
| Changelog | Release history |
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")),
)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
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,
)result = solver.turnstile(
sitekey="0x4AAAAAAA...",
url="https://example.com",
)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"]# 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"},
)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/
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.
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 exceededgit 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]"
pytestSee CONTRIBUTING.md for the full development workflow.
MIT — see LICENSE.