GeeTest v4 на Python: прочитайте ID один раз, решайте каждую отправку

geetest v4 in python - GeeTest v4 in Python: Read the ID Once, Solve Every Post

GeeTest v4 на Python сводится к одному идентификатору и одному вызову на каждую отправку формы. Прочитайте captcha_id со страницы один раз, запросите пропуск у solver.geetest_v4() из CapSkip SDK и отправьте обратно пять возвращённых значений, captcha_id, lot_number, pass_token, gen_time и captcha_output, под теми же именами. Решение выполняет сервис CapSkip для GeeTest v4 на вашем собственном ПК с Windows по фиксированной лицензии, поэтому отклонённый пропуск стоит ещё одного решения и никакой доплаты. Перед каждой попыткой ничего запрашивать не нужно, и этим он отличается от пары gt и challenge в потоке GeeTest v3.

Что понадобится для решения GeeTest v4

  • CapSkip 5.0.0 или новее на Windows (в журнале изменений решение GeeTest v4 указано в этой версии, 14 ноября 2026) и Python SDK 1.8.0 или новее (16 ноября 2026). Раздел GeeTest v4 документации API описывает запрос.
  • Python 3.10 или новее: это минимальная версия, которую заявляют capskip 1.8.0 и requests 2.34.2. Я запускал Python 3.11.7, 3.13.7 и 3.14.0 на Windows 11. Установите оба пакета командой python -m pip install capskip requests. Пакет capskip также устанавливает httpx и aiofiles, которые нужны только асинхронному клиенту.
  • Адрес для CapSkip. В Local mode (127.0.0.1) он доступен только с ПК, на котором запущен. В Server mode он слушает вместо этого вашу сеть или публичный IP, поэтому скрипты с других машин могут к нему обратиться. Где переключается режим, показывает раздел Настройки подключения руководства по настройке.

Я тестировал на двух собственных имитациях серверов: одна заменяет CapSkip, другая заменяет сайт с формой комментариев. Реального решения не было, поэтому реального времени решения у меня нет, а все правила сайта в имитации мои. На настоящем сайте бэкенд пересылает пять значений в GeeTest с подписью, сделанной его приватным ключом. Как именно, описывает справочник по серверному API GeeTest подробно. Имитация не может показать, что настоящий бэкенд хоть что-то принимает.

Шаг 1: найдите captcha_id на странице

Сохраните первый блок как comment_geetest.py и добавляйте в конец файла каждый следующий блок по порядку. Файл будет готов после шага 3. Укажите в PAGE_URL страницу, на которой показан виджет. В Server mode впишите в host адрес машины с CapSkip.

# python -m pip install capskip requests
import re

import requests
from capskip import ApiException, CapSkip

PAGE_URL = "https://example.com/comment"  # the page that shows the widget
FIELDS = ("captcha_id", "lot_number", "pass_token", "gen_time", "captcha_output")

# Local mode. In Server mode, use the address of the CapSkip machine.
solver = CapSkip(host="127.0.0.1", port=8080)

captcha_id публичный и одинаковый для всех посетителей, поэтому читайте его один раз и используйте повторно. Страница передаёт его в initGeetest4 как параметр captchaId, а скрипт виджета также отправляет его как параметр запроса captcha_id в запросе к gcaptcha4.geetest.com/load. Страница CapSkip для GeeTest v4 описывает 32-символьный идентификатор, но SDK формат не проверяет, поэтому шаблон принимает любые символы слов или дефисы. Он ищет параметр по имени, а не разбирает вызов, поэтому справляется с вложенностью, одинарными кавычками и другим порядком ключей.

def read_captcha_id(html):
    """Return the captcha_id the page gives to the GeeTest v4 script."""
    for pattern in (
        r"\bcaptchaId[\"']?\s*:\s*[\"']([\w-]+)[\"']",  # initGeetest4({captchaId: ...})
        r"[?&]captcha_id=([\w-]+)",  # a gcaptcha4.geetest.com/load address
    ):
        found = re.search(pattern, html)
        if found:
            return found.group(1)
    raise RuntimeError("no captcha_id in the page, read it from the Network tab")


def open_session():
    session = requests.Session()
    page = session.get(PAGE_URL, timeout=30)  # cookies arrive with the page
    return session, read_captcha_id(page.text)

Я запустил read_captcha_id на шести страницах имитации: идентификатор в двойных кавычках, в одинарных среди других параметров, во вложенном объекте с ключом в кавычках, не первым по порядку, в переменной, где ключ стоит последним, только в адресе загрузки и нигде, потому что скрипт строит вызов во время выполнения. В последнем случае один раз откройте вкладку Network браузера, отфильтруйте по gcaptcha4 и скопируйте captcha_id из запроса load. Функцию на настоящем сайте я не запускал.

Шаг 2: запросите пропуск через geetest_v4()

Сигнатура метода: solver.geetest_v4(captcha_id, url, **options). SDK отправляет задание, опрашивает результат, пока ответ не будет готов, и возвращает словарь, поэтому цикл ожидания не нужен. В url передайте полный адрес страницы, на которой стоит виджет. Блок ниже оставляет только пять полей для формы и добавляет risk_type, только если вы его задали.

def pick(result):
    if result.get("isOffline"):
        print("offline pass: the site decides whether to accept it")
    missing = [name for name in FIELDS if name not in result]
    if missing:
        raise RuntimeError(f"GeeTest answer did not parse, missing {missing}")
    return {name: result[name] for name in FIELDS}


def get_pass(captcha_id, risk_type=None):
    options = {"risk_type": risk_type} if risk_type else {}
    return pick(solver.geetest_v4(captcha_id, PAGE_URL, **options))

Словарь содержит пять значений как отдельные ключи. Также в нём есть captchaId, номер, который CapSkip присвоил заданию. Это не идентификатор виджета: форме нужен captcha_id с подчёркиванием. Ключ code хранит исходную строку JSON, в которую, согласно документации API, res.php упаковывает пять значений. SDK разбирает её за вас, и на моей имитации, которая следует документации, code была строкой, разбираемой в пять значений. Отправляйте отдельные поля, а не code.

Если GeeTest недоступен, его виджет пропускает посетителя в офлайн-режиме, и в словаре дополнительно появляется isOffline со значением True. В остальных случаях ключа нет. Функция pick печатает заметку и всё равно возвращает пять полей, потому что принять офлайн-пропуск или нет, решает сайт.

Параметр risk_type нужен для сайтов, которые позволяют вызывающему выбрать тип задания. По документации API допустимы значения slide, icon, nine, word, phrase, match, winlinze, svg_seed, svg_icon и ai, и GeeTest применяет одно из них, только если сайт это разрешает, так что в остальных случаях не указывайте его. SDK проверяет лишь то, что это строка: slide и nine дошли до имитации без изменений, riskType был переименован в risk_type, и придуманное значение вроде risk_type=bogus тоже ушло на сервер.

До отправки чего-либо SDK выбрасывает ValidationException, если captcha_id отсутствует, пуст или не является строкой, если адрес страницы пуст или не является абсолютным URL с http или https, если risk_type не строка, если riskType и risk_type заданы с разными значениями и если передан любой параметр, которого нет в API. Сюда относится userAgent, который принимают методы hCaptcha и MTCaptcha, а этот метод нет, и имена gt и challenge из v3. На порту, где нет сервера, каждая из этих ошибок возникала менее чем за сотую долю секунды. Для тех же ошибок в документации API указаны ERROR_PAGEURL и ERROR_BAD_PARAMETERS, поэтому тот, кто обращается к in.php напрямую, видит эти коды там, где вы видите исключение.

Метод geetest_v4() запускает настоящий браузер внутри CapSkip, поэтому SDK даёт ему recaptchaTimeout, по умолчанию 300 секунд, а не defaultTimeout. Я проверил оба. При defaultTimeout 3 секунды и имитации, которая никогда не отвечала, вызов продолжал опрос и через 9 секунд. При recaptchaTimeout 3 он выбросил TimeoutException через 3.76 секунды, потому что SDK спрашивал на 0, 0.25, 0.76 и 1.76 секунды, ещё 2 секунды ждал и только потом смотрел на срок. То же расписание задерживает и успех: пропуск, готовый через 1 секунду, вернулся на 1.76, готовый через 2 секунды на 3.76, а готовый через 6 секунд на 7.76. Это Python 3.14.0, capskip 1.8.0 и опрос по умолчанию, на имитации. На странице CapSkip для GeeTest v4 указано от 1 до 4 секунд для прохождения одним кликом и от 15 до 20 секунд для слайдера, поэтому подбирайте recaptchaTimeout под самый медленный тип, который может показать ваш сайт.

Шаг 3: отправьте пять значений, затем снова решите для следующей отправки

Отправьте пять значений под названными выше именами рядом с вашими полями и сверьте с тем, что отправляет собственная отправка страницы на вкладке Network. Функция также отправляет страницу как Referer. Библиотека requests не добавляет ни Referer, ни Origin, а некоторые фреймворки отклоняют отправку формы по HTTPS без них обоих, как моя имитация, ответившая 403.

POST_URL = PAGE_URL  # the form's action address, if it differs from the page


def post_comment(session, fields, author, text):
    return session.post(
        POST_URL,
        data={"author": author, "comment": text, **fields},  # your form's own fields
        headers={"Referer": PAGE_URL},  # requests sends none by itself
        timeout=30,
    )

Решайте заново для каждой отправки формы. Так сказано в документации API, и моя имитация ей следует: она отклонила повторную отправку тех же пяти значений как уже использованных, а также пропуск, отправленный через 3 секунды после решения при сроке жизни 2 секунды. Поэтому цикл запрашивает пропуск внутри цикла по комментариям, а captcha_id берётся один раз из open_session. Новое решение запрашивается, только если пришёл ERROR_CAPTCHA_UNSOLVABLE или сайт сообщает, что проверка капчи не пройдена. Любое другое ApiException поднимается, потому что неверный ключ снова приведёт к тому же результату.

Отказ определяется по целой фразе вашего сайта, здесь captcha check failed. Проверка по одному слову captcha совпала со страницей комментария, показанной снова после пустого комментария: на ней всё ещё есть разметка виджета. В итоге были потрачены три задания на ошибку, не связанную с капчей. Более короткая фраза check failed совпала со страницей 403 от проверки Referer.

def submit_all(session, captcha_id, comments, passes=None):
    saved = 0
    for index, (author, text) in enumerate(comments):
        for attempt in range(1, 4):
            ready = passes[index] if passes and attempt == 1 else None
            try:
                fields = ready or get_pass(captcha_id)  # a new solve per form post
            except ApiException as err:
                if "ERROR_CAPTCHA_UNSOLVABLE" not in str(err):
                    raise  # a wrong key or a bad request fails again
                print(f"comment {index + 1}, attempt {attempt}: unsolvable, new task")
                continue
            reply = post_comment(session, fields, author, text)
            if "Comment saved" in reply.text:  # your site's success sign
                saved += 1
                break
            if "captcha check failed" not in reply.text.lower():  # your phrase
                raise RuntimeError(f"refused ({reply.status_code}), not the captcha")
            print(f"comment {index + 1}, attempt {attempt}: pass refused, new solve")
        else:
            raise RuntimeError(f"comment {index + 1}: no luck after 3 attempts")
    return saved


if __name__ == "__main__":
    session, captcha_id = open_session()
    comments = [("alice", "First"), ("alice", "Second"), ("alice", "Third")]
    print(submit_all(session, captcha_id, comments), "comments saved")

Запустите командой python comment_geetest.py (py comment_geetest.py тоже работает). На имитации скрипт вёл себя одинаково на Python 3.11.7, 3.13.7 и 3.14.0:

Настройка имитацииЧто произошло
Три комментария, настройки по умолчаниюТри задания с одним captcha_id, три отправки приняты
С отправкой, написанной вручную: одни и те же пять значений отправлены дваждыВторая отправка отклонена как уже использованная
С отправкой, написанной вручную: пропуск отправлен через 3 секунды после решения, срок жизни в имитации 2 секундыОтклонён как слишком старый, следующее новое решение прошло
Два нерешаемых ответа в началеДве повторные попытки, и пропуск из третьего задания принят
Три нерешаемых ответа подрядRuntimeError, когда использованы три задания
Офлайн-пропуск, сайт его принимаетЗаметка напечатана, отправка принята после одного задания
Офлайн-пропуск, сайт его отклоняетТри задания, затем RuntimeError
Пустой комментарий, страница показана снова с разметкой виджетаRuntimeError после одного задания. При проверке по одному слову captcha три задания
Отправка формы без заголовка Referer403, RuntimeError после одного задания
Проверка ключа включена, ключ SDK по умолчаниюApiException после одного задания. С правильным apiKey принято

Читайте таблицу как проверку моей имитации и моего скрипта, а не GeeTest. Документация говорит отправлять пропуск сразу и решать заново для каждой отправки формы. Одноразовость и срок жизни в две секунды относятся к правилам моей имитации.

Несколько отправок одновременно через AsyncCapSkip

Асинхронный клиент оправдан по одной причине: пропуск готовится секунды, и три можно запросить вместе. AsyncCapSkip построен на httpx, поэтому asyncio.gather совмещает решения, а отправка форм остаётся на обычном requests. При 3.0 секунды на пропуск в имитации три отправки заняли 11.35 секунды по очереди и 4.09 секунды при совмещении, на Python 3.14.0, при трёх заданиях, открытых в имитации одновременно.

Порт 8080 в обоих блоках стоит по умолчанию для сервиса в стиле 2captcha, поэтому используйте порт, показанный в настройках CapSkip. О схеме с большим пулом читайте в статье о параллельном решении капчи на Python. Замените основной блок из шага 3 на приведённый ниже. Неудачное решение превращается в None в solve_all, а submit_all запрашивает заново одним вызовом, поэтому неверный ключ по-прежнему заканчивается тем же ApiException. Запрашивайте только столько пропусков, сколько успеете отправить, пока они свежие, а длинный список разбивайте на пакеты.

import asyncio

from capskip import AsyncCapSkip


async def solve_all(captcha_id, count):
    # Local mode. In Server mode, use the address of the CapSkip machine.
    async_solver = AsyncCapSkip(host="127.0.0.1", port=8080)
    jobs = [async_solver.geetest_v4(captcha_id, PAGE_URL) for _ in range(count)]
    results = await asyncio.gather(*jobs, return_exceptions=True)
    return [pick(r) if isinstance(r, dict) else None for r in results]


def submit_overlapped(comments):
    session, captcha_id = open_session()
    passes = asyncio.run(solve_all(captcha_id, len(comments)))
    return submit_all(session, captcha_id, comments, passes)


if __name__ == "__main__":
    comments = [("alice", "First"), ("alice", "Second"), ("alice", "Third")]
    print(submit_overlapped(comments), "comments saved")

Частые ошибки

Коды CapSkip взяты из документации API, строки с исключениями из исходного кода SDK, а последняя строка отражает моё прочтение строки документации о том, что для каждой отправки формы нужно решать заново.

ОшибкаПричинаИсправить
ValidationExceptionSDK отклонил аргументы на вашей машине, не обращаясь к CapSkip, по одной из причин из шага 2Текст исключения указывает на проблемный аргумент
ERROR_CAPTCHA_UNSOLVABLEНе удалось получить пропуск для этого заданияОтправьте новое задание, как это делает submit_all, до трёх попыток. В документации сказано, что приложение может вернуть заменяющий текст, заданный в Settings, поэтому, если вы его меняли, сверяйтесь с этим текстом
ERROR_KEY_DOES_NOT_EXIST или ERROR_WRONG_USER_KEYПриложение проверяет ключи (API Key Validation), а ваш ключ отсутствует или неверен. Вызовы без apiKey используют ключ capskip, и имитация ответила на него первым кодомПередайте свой настоящий ключ как apiKey в CapSkip()
ERROR_PROXY_FORMATВ документации этот код указан для значения proxy, которое CapSkip не может прочитать, и там просят не добавлять префикс схемы. SDK отправил значение с префиксом без измененийПишите login:password@IP:PORT без http://
NetworkExceptionНет ответа от этого хоста и порта при отправке задания: на Windows я увидел это примерно через 2 секунды. Если сервер замолчит посреди опроса, будет TimeoutExceptionУбедитесь, что CapSkip запущен и что host и port совпадают с настройками подключения
TimeoutExceptionПропуск не пришёл за recaptchaTimeout, по умолчанию 300 секунд, если вы не задали другое значениеПосмотрите задание в приложении CapSkip и запустите скрипт ещё раз
Сайт сообщает, что проверка капчи не пройденаМой вывод, а не документированный список: пять значений уже использовались, слишком старые или измененыОтправляйте каждый набор один раз и сразу, без изменений, с указанием страницы как Referer

FAQ

Можно ли вызывать CapSkip с другого компьютера?

Да, через Server mode. Включите его в настройках подключения на ПК с CapSkip, затем передайте адрес этого ПК как host в CapSkip() и ваш ключ как apiKey, если включена API Key Validation. При запуске Server mode открывает порт CapSkip для всех адресов, поэтому защитить от остальных поможет блокирующее правило Windows Firewall для машин, которым вы не доверяете. Ещё одно разрешающее правило ничего не изменит. Это по-прежнему ваша собственная машина с Windows и по-прежнему без счётчика решений.

Нужен ли прокси для GeeTest v4?

Для начала нет. В документации API сказано, что одного адреса достаточно для проверки, а ограничение частоты GeeTest нацелено на постоянный поток запросов с одного адреса. Для больших объёмов загрузите пул прокси в приложении или задайте прокси для отдельного задания, он приоритетнее пула. В статье о прокси для сервиса распознавания капчи рассказано, как выбрать прокси. В Python параметр задаётся либо словарём, proxy={"type": "HTTP", "uri": "login:password@IP:PORT"}, либо простой строкой, а рядом с ней передаётся proxytype. Обе формы дошли до имитации как поля proxy и proxytype.

А если страница выдаёт gt и challenge?

Тогда сайт работает на GeeTest v3, которому для каждой попытки нужен новый challenge и который возвращает challenge, validate и seccode. Этот поток разобран в статье о GeeTest v3 на Python.

Коротко

GeeTest v4 на Python сводится к одному captcha_id, прочитанному один раз, одному решению на каждую отправку формы и пяти полям, отправляемым обратно без изменений. Дело в том, что CapSkip даёт безлимитный сервис распознавания капчи на вашем собственном ПК, поэтому повторное решение ничего не добавляет к счёту. На странице сервиса распознавания капчи для Python перечислены вызовы SDK для остальных типов.