API для Cloudflare Turnstile: параметры, примеры и ошибки

Капча Cloudflare Turnstile стала одной из самых частых проверок в автоматизации. В отличие от старых капч, где нужно кликать по картинкам, Turnstile работает в фоне и часто не требует от пользователя никаких действий. Посетителям это удобно, а вот парсерам, инструментам тестирования и любой автоматизации на сайтах с Turnstile она мешает. В этом руководстве разбираем, как устроена Turnstile, почему она останавливает скрипты и как получить токен через API Cap.Guru.

Посмотреть, как работает виджет, можно на демо-странице Cloudflare Turnstile. Обзор капчи и способов её решения есть на странице о решении Cloudflare Turnstile.

Как решить Cloudflare Turnstile пошагово

Процесс простой: вы берёте со страницы два параметра, отправляете их в API, получаете токен и подставляете его в форму. Распознавать картинки не нужно.

Что нужно

Как найти параметры (нажмите, чтобы раскрыть)

Решается так же, как токены reCAPTCHA. Параметры можно найти в инструментах разработчика браузера.

1. Найдите sitekey в коде страницы или в JS-файле. Обычно он стоит в атрибуте data-sitekey у элемента с виджетом или в свойстве sitekey вызова turnstile.render(). Иногда его видно в адресе iframe виджета:

https://challenges.cloudflare.com/cdn-cgi/challenge-platform/h/b/turnstile/if/ov2/av0/rcv0/0/iqiy3/1x00000000000000000000AA/light/normal

2. Запишите полный адрес страницы, где стоит виджет.

Для этого примера нужны:

• адрес страницы: https://react-turnstile.vercel.app/basic
• sitekey: 1x00000000000000000000AA

Отправка задачи

http://api.cap.guru/in.php

Параметр	Тип	Обязателен	Описание
key	Строка	Да	Ваш API-ключ. Его можно посмотреть в личном кабинете
method	Строка	Да	turnstile: сообщает сервису, что вы решаете Cloudflare Turnstile
sitekey	Строка	Да	Значение data-sitekey со страницы, например 1x00000000000000000000AA
pageurl	Строка	Да	Полный адрес страницы с виджетом, например https://react-turnstile.vercel.app/basic
json	Число По умолчанию: 0	Нет	0: сервер вернёт ответ простым текстом 1: сервер вернёт ответ в формате JSON

Пример запроса

http://api.cap.guru/in.php?key=YOUR_APIKEY&method=turnstile&sitekey=1x00000000000000000000AA&pageurl=https://react-turnstile.vercel.app/basic

Пример ответа

В случае успеха вы получите OK|65787087 или, с json=1:

{
  "status": 1,
  "request": "65787087"
}

Если номер задачи не пришёл, посмотрите полный список возможных ошибок.

Получение результата

Подождите 10–15 секунд и запросите результат:

https://api.cap.guru/res.php?key=YOUR_APIKEY&action=get&id=65787087

Если задача решена, в ответе будет токен Turnstile. Если нет, придёт CAPCHA_NOT_READY: подождите 5 секунд и повторите запрос. Среднее время решения от 10 до 30 секунд.

Подстановка токена

Найдите на странице скрытое поле cf-turnstile-response и запишите в него токен. В браузерной автоматизации сделайте это через JavaScript и, если сайт использует callback, вызовите его. При прямых HTTP-запросах передайте токен параметром cf-turnstile-response вместе с остальными полями формы.

Что такое капча Cloudflare Turnstile

Turnstile — замена традиционным капчам от Cloudflare, запущенная в конце 2022 года. Её идея — подтверждать, что посетитель человек, не заставляя его решать головоломки. Вместо картинок Turnstile запускает в браузере серию тихих проверок: отпечатки canvas и WebGL, вычисления proof of work, проверки API браузера и поведенческие сигналы. Пользователь при этом ничего не видит или видит короткий индикатор проверки.

У виджета три режима:

Режим	Что видит пользователь	Что происходит
Managed	Ничего или чекбокс	Turnstile сам решает, пропустить посетителя после фоновых проверок или показать чекбокс
Non-Interactive	Виджет с индикатором проверки	Проверка проходит без действий пользователя
Invisible	Ничего	Виджет не показывается, все проверки в фоне

Независимо от режима, результат один: подписанный токен, который сервер сайта проверяет у Cloudflare. Без действительного токена запрос не пройдёт, поэтому решение Turnstile всегда сводится к получению токена.

Почему скрипты не проходят проверку

Если вы пробовали открыть страницу с Turnstile через requests или простой Selenium, вы уже знаете, что это не работает.

Turnstile требует настоящего выполнения JavaScript. Виджет запускает код в браузере, выполняет proof of work и собирает отпечаток из десятков сигналов, которые есть только в реальном браузере. Обычный HTTP-запрос этого не умеет.

Headless-браузерам тоже непросто. Turnstile смотрит на флаг navigator.webdriver, на строку WebGL-рендерера (headless Chrome на сервере обычно сообщает программный рендерер вроде llvmpipe вместо видеокарты) и на отпечаток canvas. Если что-то не сходится, проверка тихо не проходит, и токен не выдаётся.

Кроме того, Cloudflare учитывает репутацию IP: адреса облачных провайдеров (AWS, Hetzner, DigitalOcean) изначально вызывают больше подозрений.

Поэтому проще получить токен через API, чем добиваться, чтобы ваш браузер сам прошёл все проверки.

TIP

Токены Turnstile одноразовые и действуют около 5 минут. Используйте токен сразу после получения: устаревший токен — самая частая причина отказов.

Turnstile и страница проверки Cloudflare

Это две разные вещи, их часто путают.

Turnstile — виджет, который владелец сайта встраивает в свою страницу, обычно в форму. Он выдаёт токен. Его можно встретить на любом сайте, даже не работающем через Cloudflare. Sitekey есть в коде страницы, и описанный выше способ работает именно для него.

Страница проверки Cloudflare (Challenge Page) — полноэкранная страница «Checking your browser…», которую Cloudflare показывает перед входом на сайт. Она выдаёт cookie cf_clearance, привязанный к IP, User-Agent и TLS-отпечатку браузера. Метод turnstile в API для неё не предназначен: он возвращает токен для виджета на странице, а не cookie для входа на сайт.

Интеграция с Selenium, Puppeteer и Playwright

Подставить полученный токен — самая простая часть.

В Selenium установите значение поля cf-turnstile-response через execute_script. Поле находится в основном документе страницы, а не внутри iframe виджета, так что переключаться на фрейм не нужно:

driver.execute_script('document.querySelector("[name=cf-turnstile-response]").value = arguments[0]', token)

В Puppeteer и Playwright то же самое делается через page.evaluate(). Если сайт после проверки вызывает callback, вызовите его после подстановки токена. Имя callback видно в атрибуте data-callback у виджета или в вызове turnstile.render().

При отправке форм прямыми HTTP-запросами добавьте параметр cf-turnstile-response в тело POST-запроса вместе с остальными полями. Браузер не нужен.

Готовые примеры на Python, JavaScript, PHP, C# и cURL есть в статье с примерами кода.

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

Просроченный токен. Токен живёт около 5 минут и подходит для одной проверки. Если между получением токена и отправкой формы проходит много времени, сервер его отклонит. Запрашивайте токен прямо перед отправкой.

Неправильный sitekey. Некоторые сайты загружают sitekey через JavaScript, и в статическом HTML его нет. Тогда ищите запросы к challenges.cloudflare.com на вкладке Network или берите значение из DOM после загрузки страницы.

Sitekey и адрес с разных страниц. Берите оба значения с той страницы, где реально проходите проверку.

Сайт использует action или cdata. Некоторые сайты передают виджету дополнительные значения data-action и data-cdata и проверяют их на сервере. API Cap.Guru принимает для Turnstile только sitekey и pageurl, поэтому на таких сайтах токен может не пройти серверную проверку.

Сайт проверяет IP. Сайт может передавать Cloudflare IP-адрес посетителя при проверке токена. Тогда токен, полученный через API, может быть отклонён, если форма отправляется с другого адреса.

WARNING

Если токены постоянно отклоняются, проверьте по порядку: свежесть токена (используйте сразу и один раз), sitekey и адрес (с одной страницы), не передаёт ли сайт action или cdata.

Работа с большими объёмами

Отправляйте задачи параллельно. Не ждите одного токена, прежде чем запросить следующий: Cap.Guru принимает задачи параллельно, и токены можно обрабатывать по мере готовности.

Кешируйте sitekey. Для конкретного сайта он меняется редко. Найдите его один раз и используйте повторно, не загружая страницу каждый раз.

Следите за процентом успеха. Если он начал падать, проверьте, не изменились ли на сайте sitekey, action или cdata: чаще всего причина в обновлении настроек Turnstile на сайте.

Почему Cap.Guru для Cloudflare Turnstile

Turnstile отличается от капч с картинками: здесь нечего распознавать, всё сводится к получению действительного токена. Cap.Guru выдаёт токены Turnstile через API по стандартной схеме «отправить задачу — получить результат», которая подходит для любого языка: Python, Node.js, PHP, Go, Java. Токены работают для всех трёх режимов виджета: Managed, Non-Interactive и Invisible. Время решения обычно от 10 до 30 секунд.

Если ваш парсер, инструмент тестирования или автоматизация останавливается на Turnstile, это простой способ получить токен без борьбы с проверками браузера.