CaptchaSonic Selenium Python Examples

Solve any CAPTCHA in your Selenium scripts with 3 lines of Python.

Official integration examples for using CaptchaSonic with Selenium WebDriver in Python.

---

Why CaptchaSonic?

# ❌ Other services — 20+ lines of manual API polling:
import requests, time

res = requests.post("https://api.othercaptchaservice.com/createTask", json={...})
task_id = res.json()["taskId"]
while True:
    time.sleep(3)
    res = requests.post("https://api.othercaptchaservice.com/getTaskResult", json={"taskId": task_id})
    if res.json().get("status") == "ready":
        token = res.json()["solution"]["gRecaptchaResponse"]
        break
# ... inject token ...

# ✅ CaptchaSonic — 3 lines:
from captchasonic import CaptchaSonic

client = CaptchaSonic("sonic_your_key_here")
result = client.solve_recaptcha_v2_token(website_url=url, website_key=sitekey)
token = result["solution"]["gRecaptchaResponse"]

CaptchaSonic handles polling, retries, and error mapping internally — via a native gRPC connection (no HTTP overhead).

---

Supported CAPTCHAs

CAPTCHA Type	Method	Example
reCAPTCHA v2	Token injection + Script solve	examples/recaptcha_v2/
reCAPTCHA v3	Score token injection	examples/recaptcha_v3/
Cloudflare Turnstile	Token injection	examples/turnstile/
Geetest v4 (nine-grid)	Script solve	examples/geetest/
AWS WAF Captcha	Script solve	examples/aws_waf/
Image-to-Text / OCR	Text extraction	examples/image_captcha/
Popular Captcha	Token + Script solve	examples/popularcaptcha/

---

Quick Start

1. Install dependencies

pip install -r requirements.txt

Python 3.9+ required.

2. Set your API key

Get your key at captchasonic.com → Dashboard → API Keys.

export CAPTCHASONIC_API_KEY=sonic_your_key_here

Or create a .env file in the project root:

CAPTCHASONIC_API_KEY=sonic_your_key_here

3. Run an example

# reCAPTCHA v2 — token method (fastest)
python examples/recaptcha_v2/token_method.py

# reCAPTCHA v2 — script method (no extension needed)
python examples/recaptcha_v2/script_method.py

# reCAPTCHA v3
python examples/recaptcha_v3/score_token.py

# Cloudflare Turnstile
python examples/turnstile/turnstile_solver.py

# Geetest v4
python examples/geetest/script_method.py

# AWS WAF
python examples/aws_waf/script_method.py

# Image-to-Text
python examples/image_captcha/image_to_text.py

# Popular Captcha
python examples/popularcaptcha/script_method.py

---

Integration Patterns

Token Method (fastest)

CaptchaSonic solves the captcha server-side and returns a bypass token. You inject the token into the page's hidden form fields and submit.

Your script → CaptchaSonic API → returns token → inject into page → submit

from captchasonic import CaptchaSonic
from shared.helpers import get_api_key, inject_recaptcha_token

client = CaptchaSonic(get_api_key())
result = client.solve_recaptcha_v2_token(
    website_url="https://example.com",
    website_key="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
)
token = result["solution"]["gRecaptchaResponse"]
inject_recaptcha_token(driver, token)

Best for: headless automation, CI/CD pipelines, maximum speed (5–15s)

Script Method (JS injection — no extension needed)

Injects lightweight JavaScript into the page that detects, extracts, and clicks captcha challenges using CaptchaSonic's image classification API.

Inject script → detect captcha → extract images → SDK classifies → inject clicks

from shared.solver import ScriptSolver

solver = ScriptSolver(driver, client)
result = solver.solve("popularcaptcha")  # or "recaptcha_v2", "geetest", "aws_waf"

The ScriptSolver handles the full lifecycle: detect → extract → SDK solve → inject. Works on Chrome 137+ and any Chromium-based browser.

Best for: Popular Captcha, Geetest, AWS WAF, any visual challenge captcha (30–60s per round)

	Token Method	Script Method
How it works	CaptchaSonic returns a bypass token	JS extracts tiles → SDK classifies → JS clicks
Speed	⚡ Fast (5–15s)	🐢 Moderate (30–60s per round)
Best for	Most reCAPTCHA v2/v3, Turnstile	Popular Captcha, Geetest, AWS WAF
Recommended	✅ Start here	When token method is unavailable

---

AI / Agent Implementation Guide

If you are an AI agent or LLM-based tool integrating CaptchaSonic into a Selenium workflow, follow this protocol:

Architecture

┌──────────────────┐     ┌────────────────┐     ┌────────────────┐
│  Selenium Driver │────▶│  ScriptSolver  │────▶│ CaptchaSonic   │
│  (browser ctrl)  │◀────│  (orchestrator)│◀────│ SDK (gRPC/HTTP) │
└──────────────────┘     └────────────────┘     └────────────────┘
         ↕                       ↕
   Page / iframes         JS scripts (detect/
                          extract/inject)

Token Method — Step by Step

1. Initialize SDK: client = CaptchaSonic(api_key)
2. Navigate: driver.get(target_url)
3. Solve: Call the appropriate client.solve_*_token(website_url=..., website_key=...) method
4. Extract token: result["solution"]["gRecaptchaResponse"] (or "token" or "cf-turnstile-response")
5. Inject: Use shared/helpers.py → inject_recaptcha_token(driver, token) or similar
6. Submit form: Click submit or call driver.execute_script("document.querySelector('form').submit()")

Script Method — Step by Step

1. Initialize SDK: client = CaptchaSonic(api_key)
2. Navigate to target page and wait for captcha iframe
3. Switch to challenge iframe: driver.switch_to.frame(challenge_frame)
4. Create solver: solver = ScriptSolver(driver, client)
5. Solve: result = solver.solve("popularcaptcha", timeout=120, max_retries=5)
6. Check result: result["solved"] → True means captcha is complete
7. Switch back: driver.switch_to.default_content() before interacting with main page

ScriptSolver Lifecycle (Internal)

The solve() method runs this loop internally:

1. inject(script.js) → adds global object (e.g. CaptchaSonic_PopularCaptcha)
2. detect()          → returns {found, type, solved}
3. extract()         → returns {images[], question, questionType}
4. SDK call          → sends images to CaptchaSonic API → returns answers
5. inject(solution)  → clicks correct tiles / coordinates in DOM
6. Check solved      → if newChallenge, repeat from step 3

Supported Captcha Types for ScriptSolver

captcha_type	JS Script	SDK Method
"popularcaptcha"	popularcaptcha.js	solve_popular_captcha()
"recaptcha_v2"	recaptcha-v2.js	solve_recaptcha_v2()
"geetest"	geetest.js	solve_geetest()
"aws_waf"	aws-waf.js	solve_aws_waf()

Key Files

File	Purpose
shared/solver.py	ScriptSolver class — main orchestration logic
shared/helpers.py	API key loading, token injection, balance check
scripts/*.js	Vendored JS scripts for DOM detection/extraction/injection
examples/*/token_method.py	Token-based solve (fastest, start here)
examples/*/script_method.py	Script-based solve (visual captchas)

---

Transport Options

# gRPC (default) — fastest, uses HTTP/2 binary protocol
client = CaptchaSonic("sonic_xxx")

# HTTP REST — universal fallback, works anywhere
client = CaptchaSonic("sonic_xxx", transport="http")

# Async version
from captchasonic import AsyncCaptchaSonic
client = AsyncCaptchaSonic("sonic_xxx")

---

Proxy Support

result = client.solve_recaptcha_v2_token(
    website_url="https://example.com",
    website_key="...",
    proxy="http://user:pass@host:port",
)

---

Project Structure

captchasonic-selenium-python-examples/
├── requirements.txt
├── scripts/                              # Vendored JS captcha scripts
│   ├── popularcaptcha.js
│   ├── recaptcha_v2.js
│   ├── geetest.js
│   └── aws_waf.js
├── shared/
│   ├── helpers.py                        # Token injection, balance, env
│   └── solver.py                         # ScriptSolver bridge class
└── examples/
    ├── recaptcha_v2/
    │   ├── token_method.py               # ⭐ Start here
    │   ├── grid_click_method.py
    │   └── script_method.py
    ├── recaptcha_v3/
    │   └── score_token.py
    ├── turnstile/
    │   └── turnstile_solver.py
    ├── geetest/
    │   ├── geetest_v4_nine_grid.py
    │   └── script_method.py
    ├── aws_waf/
    │   ├── waf_solver.py
    │   └── script_method.py
    ├── image_captcha/
    │   └── image_to_text.py
    └── popularcaptcha/
        ├── token_method.py
        └── script_method.py

---

Links

• 🌐 CaptchaSonic
• 📦 PyPI: captchasonic
• 📖 Docs
• 🤖 n8n Node
• 🔧 MCP Server
• 🎮 Playwright Examples
• 🎯 Puppeteer Examples

---

License

MIT © CaptchaSonic