Python client for YesCaptcha hCaptcha image classification — solve 9-grid tile selection, click-position, and drag puzzles via the HCaptchaClassification API.

hcaptcha-solver

Solve hCaptcha image challenges using YesCaptcha’s HCaptchaClassification endpoint. Send captcha tile images as base64, get back which tiles to click, pixel coordinates, or drag paths.

Suggested GitHub repo description (paste into About):

Python client for YesCaptcha HCaptchaClassification — grid, click, and drag puzzle solving

Features

• Grid classification — 9-tile (or multi-tile) “select all matching images” challenges
• Click position — single-image “click the target” challenges
• Drag puzzles — drag-element-to-shape challenges
• Balance check — verify API key and account points
• Doc sample test — test_solver.py runs the official API example

Requirements

• Python 3.9+
• YesCaptcha account and client key (sign up)

Setup

git clone https://github.com/YOUR_USERNAME/hcaptcha-solver.git
cd hcaptcha-solver
pip install -r requirements.txt
cp .env.example .env

Edit .env and set your YesCaptcha client key:

YESCAPTCHA_CLIENT_KEY=your_client_key_here
HEADLESS=true

Quick start

import os

from dotenv import load_dotenv

from hcaptcha_solver import HCaptchaSolver

load_dotenv()
solver = HCaptchaSolver(os.environ["YESCAPTCHA_CLIENT_KEY"])

# 9-grid classification
result = solver.classify_grid(
    queries=[base64_img1, base64_img2, ...],  # no data: URI prefix
    question="请单击每个包含卡车的图像。",
    anchors=[anchor_base64],  # optional helper image from top-right
)

print(result["solution"]["top_k"])   # tile indexes to click, e.g. [0, 3, 4, 6, 7]
print(result["solution"]["objects"]) # True/False per tile

API methods

Method	Use case	Returns
classify_grid()	Multi-tile grid captcha	top_k, objects, confidences
classify_click()	Click on canvas image	box as [x, y, ...]
classify_drag()	Drag puzzle screenshot	box with start / end coords
get_balance()	Check account points	balance

Click position

result = solver.classify_click(
    query=canvas_base64,
    question="Please click the center of the seahorses head",
)
print(result["solution"]["box"])

Drag puzzle

result = solver.classify_drag(
    query=f"data:image/jpeg;base64,{screenshot_base64}",
    question="Please click, hold, and drag the element on the right to the shape that is most similar",
)
print(result["solution"]["box"])

Test

API sample (offline doc images)

python test_solver.py

Runs a balance check and the grid example from the official docs (uses sample images in samples.json).

Live browser test (Playwright)

pip install -r requirements.txt
python -m playwright install chromium
python test_browser.py

Opens the official hCaptcha demo, captures the live challenge canvas, sends it to YesCaptcha, clicks the returned coordinates, and submits. Supports multi-round challenges (up to 5 rounds).

Set HEADLESS=false in .env to watch the browser solve the captcha.

Project layout

hcaptcha-solver/
├── hcaptcha_solver.py   # YesCaptcha API client
├── browser_solver.py    # Playwright live demo automation
├── test_solver.py       # Offline API test (doc samples)
├── test_browser.py      # Live Playwright demo test
├── extract_samples.py   # Regenerate doc sample images
├── samples.json         # Doc example base64 images
└── requirements.txt

Notes

• Keep your client key in .env only — it is gitignored and never committed.
• Each grid solve costs 8 points on YesCaptcha.
• queries must be raw base64 (no data:image/...;base64, prefix), except drag tasks which accept a data URI string.
• Either question or anchors (or both) is required for grid tasks.

License

MIT