Python модуль

Используется Python для автоматического решения капчи.
Поддерживает клики по изображениям, перетягивание ползунка и другие типы.
Умеет сам определять тип капчи на странице.

Актуальная версия:

Версия	Изменения	Скачать
0.4	Глобальное обновление	PyPI · Скачать
0.3	Добавили AWS WAF (Amazon)	Скачать
0.2	Фикс хкапчи	Скачать
0.1	Initial release	Скачать

Установка

Модуль опубликован на PyPI:

pip install capguru
playwright install chromium

Обновление до последней версии:

pip install -U capguru

Импорт в коде не меняется:

python

from captcha_solver import CaptchaSolver, CapGuruFatalError

Установка без pip

Скачайте архив из таблицы версий и скопируйте папку captcha_solver в свой проект, рядом со скриптом.
Зависимости установите вручную:

pip install playwright httpx Pillow
playwright install chromium

Если модуль установлен через pip, не держите рядом со скриптом папку captcha_solver: Python возьмёт её, а не установленную версию.

Как использовать

Импортируйте CaptchaSolver из пакета.
Создайте солвер до перехода на страницу с капчей и вызовите await solver.setup().
Затем откройте страницу и вызовите await solver.auto() — модуль сам найдёт капчу и решит её.
Если тип капчи известен заранее, можно вызвать нужный метод напрямую.

python

solver = CaptchaSolver(page=page, api_key='YOUR_KEY', debug=True)
await solver.setup()

await page.goto('https://site.com/cap')

kind = await solver.auto(timeout=30)
print('Captcha:', kind or 'not found')

Почему солвер создаётся до перехода на страницу

При создании солвер начинает запоминать картинки капчи, которые загружает браузер, и переключает hCaptcha на английский язык. Если создать его после page.goto(), картинки первой загрузки будут пропущены, а hCaptcha может остаться на языке сайта.

Примеры

# pip install playwright playwright-stealth httpx Pillow
# playwright install chrome

import asyncio
from playwright.async_api import async_playwright
from playwright_stealth import Stealth
from captcha_solver import CaptchaSolver, CapGuruFatalError


async def main():
    async with async_playwright() as p:
        browser = await p.chromium.launch(
            headless=False,
            channel="chrome",
            args=["--disable-blink-features=AutomationControlled"],
        )
        page = await browser.new_page()
        await Stealth().apply_stealth_async(page)

        solver = CaptchaSolver(
            page=page,
            api_key='YOUR_KEY',
            debug=True,
            attempts=5,
        )
        await solver.setup()

        await page.goto('https://site.com/cap')

        try:
            kind = await solver.auto(timeout=30)
            print('Captcha:', kind or 'not found')
        except CapGuruFatalError as e:
            print('API key or balance problem:', e)

        await browser.close()

asyncio.run(main())

# pip install playwright httpx Pillow
# playwright install chromium

import asyncio
from playwright.async_api import async_playwright
from captcha_solver import CaptchaSolver, CapGuruFatalError


async def main():
    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=False)
        page = await browser.new_page()

        solver = CaptchaSolver(
            page=page,
            api_key='YOUR_KEY',
            debug=True,
            attempts=5,
        )
        await solver.setup()

        await page.goto('https://site.com/cap')

        try:
            kind = await solver.auto(timeout=30)
            print('Captcha:', kind or 'not found')
        except CapGuruFatalError as e:
            print('API key or balance problem:', e)

        await browser.close()

asyncio.run(main())

# pip install playwright httpx Pillow
# playwright install firefox

import asyncio
from playwright.async_api import async_playwright
from captcha_solver import CaptchaSolver, CapGuruFatalError


async def main():
    async with async_playwright() as p:
        browser = await p.firefox.launch(headless=False)
        page = await browser.new_page()

        solver = CaptchaSolver(
            page=page,
            api_key='YOUR_KEY',
            debug=True,
            attempts=5,
        )
        await solver.setup()

        await page.goto('https://site.com/cap')

        try:
            kind = await solver.auto(timeout=30)
            print('Captcha:', kind or 'not found')
        except CapGuruFatalError as e:
            print('API key or balance problem:', e)

        await browser.close()

asyncio.run(main())

# pip install undetected-chromedriver playwright httpx Pillow
# Chrome browser must be installed

import asyncio
import undetected_chromedriver as uc
from playwright.async_api import async_playwright
from captcha_solver import CaptchaSolver, CapGuruFatalError


async def main():
    driver = uc.Chrome(headless=False)
    try:
        address = driver.capabilities['goog:chromeOptions']['debuggerAddress']
        async with async_playwright() as p:
            browser = await p.chromium.connect_over_cdp(f'http://{address}')
            page = browser.contexts[0].pages[0]

            solver = CaptchaSolver(
                page=page,
                api_key='YOUR_KEY',
                debug=True,
                attempts=5,
            )
            await solver.setup()

            await asyncio.to_thread(driver.get, 'https://site.com/cap')

            try:
                kind = await solver.auto(timeout=30)
                print('Captcha:', kind or 'not found')
            except CapGuruFatalError as e:
                print('API key or balance problem:', e)
    finally:
        driver.quit()

asyncio.run(main())

# pip install selenium playwright httpx Pillow
# Chrome browser and chromedriver must be installed

import asyncio
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from playwright.async_api import async_playwright
from captcha_solver import CaptchaSolver, CapGuruFatalError


async def main():
    options = webdriver.ChromeOptions()
    # options.add_argument('--headless=new')
    service = Service()  # Service('/path/to/chromedriver')
    driver = webdriver.Chrome(service=service, options=options)
    try:
        address = driver.capabilities['goog:chromeOptions']['debuggerAddress']
        async with async_playwright() as p:
            browser = await p.chromium.connect_over_cdp(f'http://{address}')
            page = browser.contexts[0].pages[0]

            solver = CaptchaSolver(
                page=page,
                api_key='YOUR_KEY',
                debug=True,
                attempts=5,
            )
            await solver.setup()

            await asyncio.to_thread(driver.get, 'https://site.com/cap')

            try:
                kind = await solver.auto(timeout=30)
                print('Captcha:', kind or 'not found')
            except CapGuruFatalError as e:
                print('API key or balance problem:', e)
    finally:
        driver.quit()

asyncio.run(main())

# pip install selenium-wire undetected-chromedriver playwright httpx Pillow
# Chrome browser must be installed

import asyncio
import seleniumwire.undetected_chromedriver as uc
from playwright.async_api import async_playwright
from captcha_solver import CaptchaSolver, CapGuruFatalError


async def main():
    options = uc.ChromeOptions()
    # options.add_argument('--headless=new')
    driver = uc.Chrome(options=options, headless=False)
    try:
        address = driver.capabilities['goog:chromeOptions']['debuggerAddress']
        async with async_playwright() as p:
            browser = await p.chromium.connect_over_cdp(f'http://{address}')
            page = browser.contexts[0].pages[0]

            solver = CaptchaSolver(
                page=page,
                api_key='YOUR_KEY',
                debug=True,
                attempts=5,
            )
            await solver.setup()

            await asyncio.to_thread(driver.get, 'https://site.com/cap')

            try:
                kind = await solver.auto(timeout=30)
                print('Captcha:', kind or 'not found')
            except CapGuruFatalError as e:
                print('API key or balance problem:', e)
    finally:
        driver.quit()

asyncio.run(main())

Методы:

Автоматически:

         await solver.auto(timeout=30)   # найти капчу и решить, вернёт тип или None
         await solver.detect()           # только определить тип, не решая
         await solver.setup()            # подготовка, вызывать до page.goto()

Для конкретного типа:

         await solver.solve_recaptcha2()
         await solver.solve_hcaptcha()
         await solver.solve_other()
         await solver.solve_geetest()
         await solver.solve_funcaptcha()
         await solver.solve_tiktok()
         await solver.solve_aws()

auto() и detect() возвращают тип капчи:

Значение	Капча
`recaptcha2`	reCAPTCHA v2
`hcaptcha`	hCaptcha
`yandex`	Other
`geetest`	GeeTest v3 / v4
`funcaptcha`	FunCaptcha (Arkose Labs)
`tiktok`	TikTok
`aws`	AWS WAF
`None`	Капча не найдена за отведённое время

Поддержка капч:

reCaptcha2	FunCaptcha	TikTok	GeeTest	AWS WAF	hCaptcha	Other
Да	Да	Да	Да	Да	Да	Да

Параметры:

Параметр	Тип	По умолчанию	Описание
`page`	`Page`	—	Страница с капчей
`api_key`	`str`	—	API-ключ Cap.Guru
`attempts`	`int`	`5`	Макс. количество попыток
`debug`	`bool`	`False`	Вывод отладочных сообщений
`selector`	`str`	`''`	CSS-селектор контейнера капчи

Параметры auto():

Параметр	Тип	По умолчанию	Описание
`timeout`	`float`	`30`	Сколько секунд ждать появления капчи
`poll`	`float`	`0.5`	Как часто проверять страницу, в секундах

Обработка ошибок

При неверном API-ключе или нулевом балансе выбрасывается CapGuruFatalError — модуль сразу прекращает попытки.
Если капчу не удалось решить за все попытки, выбрасывается RuntimeError.
CapGuruFatalError — наследник RuntimeError, поэтому ловите его первым:

python

from captcha_solver import CaptchaSolver, CapGuruFatalError

try:
    kind = await solver.auto(timeout=30)
    print('Captcha:', kind or 'not found')
except CapGuruFatalError as e:
    print('API key or balance problem:', e)
except RuntimeError as e:
    if 'ERROR_CAPTCHA_UNSOLVABLE' in str(e):
        print('Captcha was not solved after all attempts')

Python модуль ​

Актуальная версия: ​

Установка ​

Как использовать ​

Примеры ​

Методы: ​

Поддержка капч: ​

Параметры: ​

Обработка ошибок ​

Python модуль

Актуальная версия:

Установка

Как использовать

Примеры

Методы:

Поддержка капч:

Параметры:

Обработка ошибок