Ship captcha solving
in under 5 minutes

Quickstart #

Get your first solve in under 2 minutes. Three steps: create an account, grab an API key, make a request. We'll show all three languages side-by-side in the right panel — use the tabs to switch.

1. Create account & get API key

Go to visusolve.yorubacinemax.xyz/signup, sign up, and copy your key from Dashboard → API Keys. New accounts get a bonus key with 1000 free credits that expires after 30 days if unused. You can create unlimited additional keys per service/worker.

2. Install httpx (Python) or use fetch (JS)

Python: pip install httpx — 3.9+ recommended, async support built-in. Node.js 18+ has global fetch. Bun/Deno also work identically.

3. First real request — classify

Classify a reCAPTCHA v2 grid challenge. Replace sk_live_xxx with your real key. The right panel shows the full payload — base64 image can be raw or data-URI.

4. Handle dynamic refresh

Google sometimes sends a second grid after first selection (e.g. you selected 3 crosswalks, now it asks for new images with crosswalks again). Implement a loop: while response contains target tiles, click them in your automation (Selenium/Playwright) and call /classify again with new tiles. Max 3 iterations is safe; more looks bot-like.

5. Go production

• Add retry with exponential backoff on 429/500/503 (see Error Handling)
• Cache website_key parsing; don't scrape target HTML on every solve
• Use solving_id to correlate logs
• Monitor balance via GET /api/balance in a cron; alert if <100 credits

Testing with curl

All endpoints are curl-friendly. Use the cURL tab. For image heavy endpoints, save base64 to file and use $(cat file.b64).

Authentication #

All API requests are authenticated via API key. Keep keys secret—they have full access to your credits and solves.

Methods

You can authenticate using either header or query param (header preferred).

Key format

• Prefix sk_live_ for production, sk_test_ reserved for future sandbox.
• Length 48-64 chars after prefix, URL-safe alphanum.
• Example placeholder: sk_live_4eC39HqLyjWDarjtT1zdp7dcEXAMPLE

Getting a key

1. Create account at visusolve.yorubacinemax.xyz/signup
2. Verify email
3. Dashboard → API Keys → Create Key → Copy
4. Bonus key (1000 credits) auto-created; deletable after upgrade

SDKs & Libraries #

Official SDKs wrap the REST API with retry, backoff, and typed responses. Bring your own http client if you prefer.

Until SDKs ship, use the cURL/Python/JS snippets in the right panel. They are production-grade with timeouts and error handling.

reCAPTCHA v2 — POST /classify #

Primary endpoint. Classifies a reCAPTCHA v2 image challenge grid: given images (base64) and target keyword like "Select all images with traffic lights", returns boolean array of which tiles match.

Request body (JSON)

Response 200

reCAPTCHA v2 — POST /solve (browser solver) #

Full browser automation solve. You provide website_key and website_url; server spins headless browser (optional proxy) and returns a valid g-recaptcha-response token ready to POST to target site.

Response

reCAPTCHA v2 — Code examples #

Copy-paste production snippets. Handle dynamic refresh by looping until no target tiles remain (google tracks behavior).

Best practices

• Always send target_keyword lowercase, trimmed.
• For base64 images, strip data:image/...;base64, prefix server accepts both but raw is faster.
• Retry once on 429/503 with exponential backoff.
• Cache sitekey → avoid re-parsing HTML each time.

reCAPTCHA v3 — POST /api/v3/solve #

Emulates v3 client behavior and returns a valid enterprise-grade token with high score (0.7–0.9). Token must be verified server-side by target within 2 minutes.

Response

reCAPTCHA v3 — POST /api/v3/verify #

Verify a token returned from /solve before forwarding to your backend. Validates token shape, expiry, and optionally remote_ip binding.

reCAPTCHA v3 — GET /api/v3/health #

Healthcheck for v3 solver cluster. Returns uptime, model version, avg latency.

Geetest v4 — POST /api/geetest/v4/solve #

Solves Geetest v4 challenges — slide, icon, gobang, AI, invisible, winlinze captcha. Provide captcha_id (gt + challenge combined or just captcha_id) and risk_type. Returns lot_number + captcha_output + etc required to pass verification.

Response

Geetest v4 — POST /api/geetest/v4/solve-image #

Low-level image gap solver: you supply Geetest background + slice (puzzle piece) image URLs (or base64), we return gap x coordinate / slide distance. Use when you have already extracted images client-side.

Geetest v4 — GET /api/geetest/v4/health #

Healthcheck for Geetest solvers.

Management — GET /api/balance #

Returns credit balance, usage today, and bonus credits left.

Response

Management — GET /api/usage #

Daily usage breakdown, per-endpoint counts, error rate, p50/p95 latency.

Management — API Keys CRUD #

Programmatic key management. Bonus key cannot be deleted via API for safety—it requires dashboard confirmation.

Create key request

Response on create

Only time full key is returned. Store securely immediately.

Webhooks #

For long-running browser solves (/solve), optionally provide webhook_url to get async callback when token is ready instead of polling.

Browser Extension (MV3) #

Official Chrome MV3 extension auto-detects reCAPTCHA v2/v3 and Geetest v4 on any page and solves in-place using your VisuSolve key. No code changes needed.

Install

1. Download extension.zip from VisuSolve.
2. Unzip locally: unzip extension.zip -d visusolve-extension
3. Open chrome://extensions, enable Developer mode (top right toggle).
4. Click Load unpacked → select visusolve-extension folder.
5. Pin extension from toolbar puzzle icon.
6. Click extension icon → paste your sk_live_... key → Save.

How it works

• Content script observes DOM for iframe[src*="recaptcha"], div.geetest_*, #g-recaptcha, etc.
• On detection, extracts images / sitekey / url and sends to VisuSolve API via background worker.
• For v2 grid, overlays checkboxes auto-clicked; for token flow, fills g-recaptcha-response and dispatches callback.
• Extension popup shows remaining balance, toggle per-site enable/disable, and auto-solve on/off.
• No browsing data leaves device except captcha payloads directly to visusolve.yorubacinemax.xyz. No analytics.

Error handling #

Standard HTTP status + consistent JSON error shape. Always check HTTP status before parsing body.

Error response shape

Always JSON:

Rate limits #

Prevent abuse and ensure fairness. Limits are per-API-key, sliding window 60s.

Credit costs

Headers

Security best practices #

Treat API keys like passwords.

• Server-side only — never embed keys in frontend JS, mobile apps, or public repos.
• Env vars — load from VISUSOLVE_API_KEY env var or secrets manager, never hardcoded.
• Rotate regularly — use POST /api/keys/{id}/regenerate quarterly or after personnel change.
• Per-service keys — create separate keys per service (e.g. prod-worker vs staging) so you can revoke one without downtime.
• Proxy through backend — if you must solve from browser, proxy through your backend that adds X-API-Key server-side.
• Monitor usage — set up alerts on sudden spike via /api/usage.
• Webhook sig — always verify X-Webhook-Signature if using callbacks.

Data handling

We do not log image payloads. Only metadata (grid size, keyword hash, time_taken, result count) kept for metrics 7 days. ONNX inference runs in isolated sandbox, no outbound network. GDPR compliant—no PII stored beyond account email.

Pricing #

Simple credit system. 1 solve ≈ 1 credit except browser & v3/geetest flows (see rate limits). Unused credits roll over 1 month on paid plans.

Enterprise: custom volume (500k+), dedicated ONNX pool, on-prem deploy option, audit logs, SSO. Contact sales@visusolve.

Integrations & Framework Adaptors #

VisuSolve integrates with popular automation stacks via lightweight adaptors. No heavy SDK — just drop-in helpers.

Puppeteer Extra

Use puppeteer-extra + puppeteer-extra-plugin-stealth to avoid detection. VisuSolve token injection works even with stealth.

Environment variables reference

Docker

For self-hosted Enterprise: docker run -p 8000:8000 visusolve/on-prem:latest exposes same API on localhost. License key via VISUSOLVE_LICENSE env. Health at :8000/health.

Models — accuracy, latency, versioning #

We version every model. Use model_version field in responses for debugging. Pinning not supported — you always get latest stable; changelog announces improvements.

Evaluation methodology

Internal set: 12k v2 challenges scraped from google domains, balanced across 15 keywords (bus, car, traffic light, crosswalk, bicycle, fire hydrant, truck, motorcycle, boat, airplane, parking meter, bench, etc). Accuracy measured tile-level IoU >0.5 and end-to-end solve (checkbox checked). Sets rebuilt weekly to avoid overfit.

Legal & Compliance #

VisuSolve is designed for legitimate testing of your own services and automation where you have permission. You must comply with target site ToS.

• We do not condone spamming, scalping exclusive goods, or violating CFAA.
• All images are processed ephemerally — never stored, never used for retraining without explicit opt-in (Dashboard → Privacy).
• No PII in logs beyond hashed IP for rate limiting. Subprocessors: none (we host our own GPU fleet).
• DMCA / abuse: [email protected]

Rate Limits Deep Dive & Concurrency Control #

Understanding limits helps you avoid 429s and build adaptive concurrency.

Sliding window algorithm

We use Redis-backed sliding window per API key, 60s window. At 100% Pro RPM 600, you can burst 20 in first second, but remainder throttled. Use token bucket mental model: refill rate = RPM/60 per second.

Adaptive client example (pseudocode)

Start with semaphore = RPM. If 429 received, halve semaphore and sleep Retry-After. If 10 successes in row, increment semaphore by 1 until Max. This converges near limit without constant 429s.

Headers recap

Credit vs rate limit

Rate limit is requests per minute, credit is lifetime / monthly usage. You can have credits but be rate limited if too fast. Also you can have 0 credits and well under rate limit — then 402.

Testing & Sandbox #

No separate sandbox today: use bonus key for testing, 1000 credits enough for ~100 test solves. For unit tests, mock VisuSolve response: return { success: true, data: [true,false,...] } for /classify, and { token: "test_token_"+random } for /solve.

Fixtures for CI

• Save a base64 tile fixture set in repo (not the real challenge? use synthetic white images) — mock classify returns deterministic.
• Integration tests: if CI has VISUSOLVE_API_KEY, run 1 real /classify request with 1 tile grid 1x1 and keyword "bus" to assert success true and time_taken_ms <1000.
• For v3, test token shape: starts with 03AG or 03AF and length 400-1200.

FAQ #

SDKs Deep Dive — patterns #

Until official SDKs ship, here are robust integration patterns for Python httpx and Node fetch that handle retries, timeouts, and logging idiomatically.

Python sync client pattern

Wrap VisuSolve in a class with tenacity/retry. Use httpx.Client to reuse TCP connections — important at high QPS.

Python async + asyncio.gather

For bulk solving, use httpx.AsyncClient + asyncio.Semaphore(limit=10) to parallelize while respecting rate limits. Example in right panel scales to ~6 solves/sec on Pro.

Node.js batch

Use p-limit for concurrency. Set fetch timeout via AbortController. Example: solve 100 v2 grids in parallel with 10 concurrency, total ~15s.

Playwright integration

Typical flow: page.goto(url) → page.evaluate -> extract base64 tiles via canvas → call VisuSolve → page.click() on matching tiles using checkbox selectors → loop.

Changelog #

We ship weekly model improvements. No breaking changes without major version bump.

Common Playbooks #

Playbook 1: Selenium + VisuSolve v2

1. Driver finds iframe[src*="recaptcha/api2/bframe"]
2. Extract data-sitekey via JS
3. Wait for checkbox click → image challenge appears
4. Scrape .rc-imageselect-tile images as base64 via canvas.toDataURL
5. Read instruction via .rc-imageselect-instructions
6. POST /classify → get boolean mask → click tiles where true
7. Click Verify, loop if new challenge, else extract token via grecaptcha.getResponse() or via hidden textarea

Playbook 2: v3 token injection

1. Frontend loads grecaptcha via script? Extract sitekey
2. POST /api/v3/solve with sitekey + page url + action (find action in page JS, often grecaptcha.execute(key, {action: 'submit'}))
3. Receive token, inject into form: POST your form with g-recaptcha-response=TOKEN
4. Token valid ~110 sec, single use

Playbook 3: Geetest v4 from browser network tab

1. Open target site with DevTools → Network tab → filter gcaptcha4
2. Find request to /load → copy captcha_id
3. POST /api/geetest/v4/solve with captcha_id → receive lot_number etc
4. Call Geetest verify endpoint /verify with those fields + your challenge payload (docs on Geetest site)

Health & System — GET /health #

Global health check for the entire platform — model status, queue depth, and region. No auth required, suitable for uptime monitors and load-balancer health probes. Returns 200 even when degraded, check status field.

Recommended monitors

• Ping /health every 30s from your uptime checker (BetterUptime, StatusCake)
• Alert if status != ok for >2 minutes
• For Pro, monitor X-RateLimit-Remaining drop <10% as early warning to auto-buy more credits webhook (future)

Concurrency & Performance Tips #

VisuSolve is built for throughput. Median /classify latency is <400ms, p95 <650ms, p99 <950ms on Pro. Here is how to squeeze max QPS without 429s.

• Reuse connections — Use httpx.Client / fetch with keep-alive. TCP+TLS handshake is ~80ms, inference is ~140ms, so reuse saves 36%.
• Batch vs parallel — /classify accepts up to 16 images array; if you have 3x3 grid, single request is cheaper than 9 separate. For multiple pages, parallelize across pages with semaphore.
• Model warm — First request after idle may be ~30% slower due to ONNX session cold start. Send a dummy request on app boot to warm. Example: POST with 1x1 white pixel and keyword "bus" — costs 1 credit but warms model worker.
• mode=fast vs accurate — fast uses FP16 224px input tensor, accurate uses FP32 320px + TTA (horizontal flip). Use fast unless tile class is crosswalk, chimney, or traffic light in fog/night — those +1.8pp better in accurate.
• Timeout tuning — Set client timeout = server expected + 2s. For /classify: 10s client; for /solve: 90s; v3: 40s; geetest slide: 30s.
• Async bulk — Use httpx.AsyncClient + asyncio.Semaphore(10-40 depending on plan) to saturate your RPM without 429s. See right panel bulk example.
• Proxy hint — For /solve browser flow, pass fastest proxy you can; solver's headless chromium will use it for target site. If no proxy, solver uses datacenter egress which some sites block.

Latency breakdown (typical /classify)

Automation — Selenium, Playwright, Puppeteer #

Complete end-to-end examples are in the right panel (see advanced client + Playwright groups). Key ideas for each framework:

Selenium 4

• Use driver.execute_script to extract tiles via canvas (avoid screenshot cropping offset bugs especially on HiDPI).
• Click tiles using Actions API move_to_element with pause(80-150ms) to look human; Google tracks mouse trajectory for some challenges.
• Sometimes checkbox re-renders after click — wait for .rc-imageselect-dynamic-selected count to stabilize before clicking Verify.
• Disable dom.webdriver.enabled pref or use undetected-chromedriver / selenium-stealth.
• Always set realistic navigator.userAgent and languages — not headless default.

Playwright (recommended)

• Preferred for reliability + auto-wait. Use page.locator + frameLocator for bframe — outer page & checkbox are separate iframes.
• For base64, use Playwright's locator.evaluate(el => canvas) method — see right snippet. Do NOT use screenshot as it may be throttled by target's CSP.
• Enable --disable-blink-features=AutomationControlled and real user-agent; VisuSolve does not need that but target site does.
• Playwright trace viewer useful for debugging dynamic refresh loops.

Puppeteer

Similar to Playwright; use page.$eval to pull images. Remember to await page.waitForTimeout after each tile click to let Google validate (300-600ms). Enable stealth plugin puppeteer-extra-plugin-stealth.

Dynamic challenge loop detail

Google may refresh tiles after you click some. Logic:

1. Call /classify with current tiles → get mask → click true tiles.
2. Wait 400ms; check if new images loaded (compare image src or use MutationObserver via evaluate).
3. If new images, repeat from step 1 with only new tiles (some tutorials require re-classifying whole grid — safe to just classify whole 3x3 again).
4. If no new images after Verify, check for checkbox checked or new challenge. Max 4 rounds.
5. If still unsolved, fall back to /solve browser API and request a fresh token (costs 3 credits but saves manual loops).

Troubleshooting #

Common issues and fixes. Always include X-Request-Id from response headers when contacting support.

Support & SLA #

Pro plan includes 99.9% monthly uptime SLA. Credits refunded pro-rata on downtime >0.1%. Enterprise includes dedicated Slack channel + 1h initial response + 4h resolution target.

• Email: [email protected] — include X-Request-Id
• Dashboard logs: every request logs time_taken, model_version, balance remaining — searchable by solving_id
• Discord: link in dashboard footer (invite-only for Pro+ customers)
• Status page: /health — bookmark for monitors, supports HEAD as well
• Changelog: see section above — no breaking API changes without major version bump (v2 → v3 etc)

Data retention & privacy

We do not retain base64 images. Only hashed keyword + grid size + latency + result count stored 7 days for metrics. ONNX inference runs in gVisor sandboxed container, no outbound network allowed. GDPR: we store only email + hashed IP for rate limit. DPA available on request for Enterprise.

Webhook Signature Verification — Detailed #

When you configure webhook_url in /solve or /api/v3/solve, VisuSolve POSTs JSON to your endpoint within 100ms of solve completion. Verify HMAC SHA256 to prevent spoofing.

Headers

Payload shape

Verification in Python:

Compare constant-time (hmac.compare_digest). If signature missing or mismatch, respond 401.

Retry policy

Webhooks retried 3 times with exponential backoff 2s, 8s, 32s if your endpoint returns non-2xx or timeout >5s. After 3 failures, solve result stored 10min and can be fetched via management API using solving_id (future).

More Examples — Scrapy, Bulk, Error Handling #

Scrapy middleware

Intercept captcha detection in downloader middleware, pause request, solve, inject token, return request.

Retry decorator pattern

Use tenacity library: @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=10), retry=retry_if_exception_type((httpx.HTTPStatusError,))). Handles 429/503 by waiting Retry-After.

Logging structured

Always log X-Request-Id, solving_id, endpoint, time_taken_ms for post-mortem. VisuSolve dashboard logs provide server-side view; client logs complement.

Cost calculator

Estimate monthly cost: solves per day * 30 * avg credits per solve * price per credit. Example: 1000 solves/day v2 fast = 1000*30=30k credits = fits Pro $49 (50k). v3 double cost: 15k v3 solves = 30k credits = same bucket.

Migration — from 2Captcha / AntiCaptcha #

Migrating from human farms? Map their API to ours:

Benefits: 10x faster median latency, no variable queue, cheaper at scale (Pro $49/50k vs human farms $2/1000 = $100/50k), no ethical concerns.