Scarnox · Blog

Як розв'язати PopularCaptcha на Python (робочий приклад, 2026)

Якщо ваш скрипт на Python натрапив на PopularCaptcha, вам не потрібна ферма браузерів або власна модель. Вам потрібні sitekey сторінки, один POST-запит і токен, який повернеться у відповідь.

Цей посібник проведе вас від нуля до робочого токена приблизно за п'ять хвилин: отримати ключ API, знайти sitekey, запросити токен, відправити його у форму і обробити випадки невдач, які з'являються, коли скрипт працює без нагляду. Невдалі розв'язання безкоштовні, тож повтор коштує лише часу.

Scarnox розв'язує PopularCaptcha сьогодні, з проксі або без. Інші типи капчі, наприклад reCAPTCHA, Cloudflare Turnstile і AWS WAF, скоро з'являться, тому всі приклади тут використовують PopularCaptcha. Огляд типів капчі пояснює, чим вони відрізняються.

1. Отримайте ключ API

Створіть обліковий запис і почніть з безкоштовного пробного кредиту, картка не потрібна. Ваш ключ API є на панелі керування. Тримайте його поза вихідним кодом і читайте зі змінної середовища:

export SCARNOX_KEY="scarnox_YOURAPIKEY"

2. Знайдіть sitekey

Відкрийте сторінку з капчею, відкрийте DevTools і знайдіть у панелі Elements data-sitekey. Sitekey PopularCaptcha - це UUID:

<div class="h-captcha" data-sitekey="10000000-ffff-ffff-ffff-000000000001"></div>

Немає data-sitekey у HTML? Віджет, імовірно, рендериться через JavaScript. Перевірте вкладку Network на запит конфігурації віджета; його параметр запиту sitekey - це потрібне значення. Інші способи знайти його описують URL iframe і невидимі віджети.

Надішліть URL сторінки, на якій показано віджет, як site_url. Найважливіше - хост, але повний URL сторінки - безпечний вибір.

3. Запросіть токен

import os
import requests

API_URL = "https://api.scarnox.com/api/tasks/create"
API_KEY = os.environ["SCARNOX_KEY"]

def solve_captcha(sitekey: str, page_url: str) -> str:
    r = requests.post(
        API_URL,
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "captcha_type": "PopularCaptchaTaskProxyless",
            "site_key": sitekey,
            "site_url": page_url,
        },
        timeout=185,  # виклик блокується, доки токен не буде готовий
    )
    data = r.json()
    if data.get("errorId") != 0:
        raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
    return data["solution"]["token"]

if __name__ == "__main__":
    token = solve_captcha("10000000-ffff-ffff-ffff-000000000001", "https://example.com/signup")
    print(token[:40], "...")

Це вся інтеграція. Циклу опитування немає, і немає другого виклику "отримати результат". Запит повертається, коли токен готовий, тож єдиний параметр, який має значення, - це тайм-аут, достатньо довгий, щоб покрити повільне розв'язання. Використовуйте близько 185 секунд.

Успішна відповідь має errorId, що дорівнює 0, а токен лежить у solution.token. Будь-яке інше значення errorId означає, що розв'язання не вдалося, і відповідь містить errorCode та errorDescription, які пояснюють причину.

4. Відправте токен

Токен потрібно передати туди, де сайт очікує відповідь на капчу. Для PopularCaptcha це майже завжди приховане поле h-captcha-response. Багато сайтів також приймають g-recaptcha-response, тому надсилайте обидва:

import requests

def sign_up(session: requests.Session, form_url: str, email: str, sitekey: str) -> requests.Response:
    token = solve_captcha(sitekey, form_url)
    return session.post(form_url, data={
        "email": email,
        "h-captcha-response": token,
        "g-recaptcha-response": token,
    }, timeout=30)

Дві деталі тут важливі. Справжні сайти зазвичай також перевіряють cookie сесії з завантаження сторінки, тож завантажуйте форму тим самим requests.Session перед POST. І надсилайте POST на action форми, яка не завжди є URL сторінки.

Розв'язуйте прямо перед відправкою. Токен спливає приблизно за дві хвилини, тож не запитуйте його на початку довгого завдання і не тримайте. Якщо сайт відхиляє токен, відкрийте форму в DevTools і підтвердіть імена прихованих полів.

5. Обробка невдач

Невдалі розв'язання безкоштовні, тож повтор коштує лише часу. Деякі помилки ніколи не вдадуться при повторі, тож не циклюйте сліпо. Перевіряйте errorId щоразу, записуйте errorCode і errorDescription і повторюйте лише тимчасові невдачі.

Мережеві помилки потребують окремої обробки, бо requests викидає виняток до того, як з'являється будь-яка відповідь:

import requests

try:
    token = solve_captcha(sitekey, page_url)
except requests.RequestException as exc:
    print("network problem, retry later:", exc)
except RuntimeError as exc:
    print("solve rejected:", exc)

Посібник з обробки помилок містить повну політику повторів з відступом і джитером.

Типові помилки

Спробуйте безкоштовно

Створіть обліковий запис і почніть з безкоштовного пробного кредиту, картка не потрібна. Запустіть приклад вище на формі, яка належить вам, перш ніж вбудовувати його у більше завдання. Вартість розв'язання в обсязі дивіться на сторінці тарифів.

Логування кожного розв'язання

Записуйте один рядок на розв'язання: sitekey, хост сторінки, errorId, errorCode при невдачі і тривалість виклику. Не записуйте ключ API і пароль проксі. Ці рядки показують, чи повільний запуск через сторінку, проксі чи розв'язувач. Вони також перше, що знадобиться, якщо ви відкриєте запит до підтримки.

Розв'язання в циклі

Якщо ваш скрипт розв'язує багато капч поспіль, тримайте цикл простим. Розв'яжіть, відправте, перевірте результат і лише потім переходьте далі. Не розв'язуйте наперед і не ставте токени в чергу, бо кожен спливає приблизно за дві хвилини. Коротка пауза між розв'язаннями на одному сайті тримає частоту запитів близькою до того, що створила б людина.

Що далі