Типы задач

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

Эта страница переведена с китайской версии машинным переводом и может содержать ошибки. Приоритет имеет китайская версия.

Just a moment...Example Domain×

‹ › ↻example.com

example.com

Проверяем, что вы человек. Это может занять несколько секунд.

Проверка...Подтвердите, что вы человекУспешно!CLOUDFLAREКонфиденциальность • Условия

Сайту example.com нужно проверить безопасность вашего соединения, прежде чем продолжить.

Just a moment...Example Domain×

‹ › ↻example.com

example.com

Проверяем, что вы человек. Это может занять несколько секунд.

Проверка...Подтвердите, что вы человекУспешно!CLOUDFLAREКонфиденциальность • Условия

Сайту example.com нужно проверить безопасность вашего соединения, прежде чем продолжить.

ИллюстрацияСтраница проверки Cloudflare закрывает всю страницу («Just a moment...»). Обычно проверка завершается сама, и браузер переходит на нужную страницу.

Страница проверки Cloudflare — это страница, которой Cloudflare закрывает весь сайт и показывает «Just a moment…» или «Checking your browser». YesCaptcha открывает страницу через ваш прокси, проходит проверку и возвращает cookie (например, cf_clearance), использованный User-Agent, заголовки запроса и ответа, а также HTML страницы после проверки. CloudFlareTaskS2 стоит 25 pts (≈ $3.75 / 1k) за задачу, CloudFlareTaskS3 — 20 pts (≈ $3.00 / 1k) за задачу. Параметры, результат и эффективность у обоих типов одинаковые, отличается только цена. Результат асинхронный: одна задача обычно занимает от 6 до 35 секунд, в зависимости от сайта время сильно различается. При неудаче или таймауте баллы возвращаются автоматически.

POSThttps://api.yescaptcha.com/createTaskГлобальный endpoint

POSThttps://cn.yescaptcha.com/createTaskEndpoint для Китая

Когда использовать

В исходном коде страницы есть __cf_chl_rt_tk или cdn-cgi/challenge-platform, а заголовок — Just a moment...: это страница проверки. Если на ней нужно поставить галочку «Verify you are human», подходит эта же страница документации.
Если проверка Cloudflare — это только виджет внутри формы, то это Turnstile, и эта страница не нужна.
Если при запросе через requests или подобную библиотеку приходит 403 и «Just a moment…», а в браузере страница открывается, скорее всего вас блокирует только TLS-отпечаток. Достаточно библиотеки, имитирующей TLS-отпечаток браузера (например, curl_cffi): проходить проверку не нужно.

Типы и цены

Тип задачи	Цена	Режим	Примечания
`CloudFlareTaskS2`	$3.75 / 1k; 25 pts/задача · ¥25 / 1k	Асинхронный	Свой прокси
`CloudFlareTaskS3`	$3.00 / 1k; 20 pts/задача · ¥20 / 1k	Асинхронный	Свой прокси

Цены в долларах США являются оценочными и рассчитаны по курсу 1 USD ≈ ¥6.67; списание за задачи производится в баллах.

Параметры запроса

Поле	Тип	Обязательное	Описание
`type`	string	Да	Тип задачи; см. «Типы задач и цены» на этой странице
`websiteURL`	string	Да	Полный URL страницы за проверкой. Должен быть публичным URL, начинающимся с `http://` или `https://`; частные IP-адреса и локальные или внутренние имена хостов, например `localhost`, отклоняются
`proxy`	string	Да	Прокси одной строкой: `http://user:[email protected]:8080` (HTTP-прокси, учётные данные необязательны) или `socks5://proxy.example.com:1080` (без учётных данных). Прокси `https://` и SOCKS5 с учётными данными не поддерживаются, локальные и частные адреса отклоняются. Все запросы к целевой странице идут через этот прокси
`userAgent`	string	Нет	Обычно не указывайте. Используется только User-Agent настольного Chrome на Linux; все остальные (Windows, macOS, мобильные, другие браузеры) игнорируются. Для последующих запросов всегда используйте `user_agent` из результата
`waitLoad`	boolean	Нет	По умолчанию false. Если true, после прохождения проверки задача ждёт, пока сетевая активность страницы утихнет, и только потом возвращает результат, поэтому в `content` попадает больше динамически загруженного содержимого; это занимает на несколько секунд больше
`requiredCookies`	array	Нет	Имена cookie, которые обязательно нужно получить, в виде массива строк, например `["cf_clearance"]`. Если параметр задан, задача считается успешной, только когда получены все они; иначе возвращается `ERROR_CAPTCHA_UNSOLVABLE` и выполняется возврат баллов. Если параметр не задан, задача всё равно пытается получить `cf_clearance`, но считается успешной (и баллы списываются) с любыми другими полученными cookie, поэтому передайте его явно, если вам нужен `cf_clearance`
`blockImage`	boolean	Нет	Если true, изображения на целевой странице не загружаются (кроме тех, которые нужны самой проверке Cloudflare), что экономит трафик прокси
`postData`	object	Нет	Если параметр задан, он отправляется на `websiteURL` как обычная HTML-форма методом POST (`application/x-www-form-urlencoded`): каждый ключ — поле формы, значения отправляются как строки, например `{"name": "hi"}`. Должен быть объектом

Требования к прокси

proxy обязателен, все запросы к целевой странице идут через этот прокси. cf_clearance привязан к выходному IP, поэтому и при последующих обращениях к сайту нужно использовать тот же прокси.

Формат	Поддержка
`http://user:[email protected]:8080`	Поддерживается: http-прокси с логином и паролем
`http://proxy.example.com:8080`	Поддерживается: http-прокси без логина и пароля
`socks5://proxy.example.com:1080`	Поддерживается: socks5-прокси без логина и пароля; `socks5h://` обрабатывается как `socks5://`
`socks5://user:[email protected]:1080`	Не поддерживается, возвращается `ERROR_PROXY_INCORRECT`; если нужны логин и пароль, используйте http-прокси
`https://proxy.example.com:443` и другие протоколы, а также адрес без порта	Не поддерживается, возвращается `ERROR_PROXY_INCORRECT`
Локальные, внутренние и зарезервированные адреса вроде `127.0.0.1`, `192.168.x.x`, `10.x.x.x` или домены, которые разрешаются в такие адреса	Отклоняется, возвращается `ERROR_PROXY_BANNED`

User-Agent

Обычно userAgent передавать не нужно. Проверку мы проходим десктопным Chrome под Linux, поэтому используется только User-Agent десктопного Chrome под Linux; остальные (Windows, macOS, мобильные устройства и другие браузеры) игнорируются: по результатам тестов, если реальное окружение браузера не совпадает с User-Agent, проверка Cloudflare не проходит. В последующих запросах всегда используйте user_agent из результата.

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

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "CloudFlareTaskS3",
    "websiteURL": "https://example.com/",
    "proxy": "http://user:[email protected]:8080",
    "requiredCookies": ["cf_clearance"]
  }
}

Чтобы использовать CloudFlareTaskS2, измените только type, остальное оставьте как есть.
Если передан requiredCookies со значением ["cf_clearance"], то при отсутствии cf_clearance задача завершается ошибкой и баллы возвращаются. Если не передавать, задача считается успешной и баллы списываются, даже когда получены только другие cookie, но не cf_clearance.
Чтобы отправить форму, добавьте postData, например {"name": "hi"}: данные будут отправлены на websiteURL как POST-форма.

После создания задачи вызывайте getTaskResult каждые 5 секунд; порядок такой же, как и у других асинхронных задач, см. getTaskResult.

Результат

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36",
    "cookies": {
      "cf_clearance": "Wq3vXk9...-1760860800-1.2.1.1-..."
    },
    "request_headers": {
      "accept-language": "en-US,en;q=0.9",
      "user-agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36"
    },
    "headers": {
      "content-type": "text/html; charset=UTF-8",
      "server": "cloudflare"
    },
    "content": "<!DOCTYPE html>..."
  }
}

Значения cookie и заголовки выше приведены для примера; ориентируйтесь на то, что вернёт API.

Поле	Тип	Описание
`cookies`	object	Все cookie в браузере после прохождения проверки (объект «имя — значение»), обычно включают `cf_clearance`; если вы передали `requiredCookies`, в ответ входит каждый из них. Используйте их вместе с возвращённым `user_agent` и прокси, который вы указали
`user_agent`	string	User-Agent, который браузер фактически использовал при прохождении проверки (десктопный Chrome на Linux). `cf_clearance` привязан к нему, поэтому используйте его во всех последующих запросах
`request_headers`	object	Заголовки запроса, которые браузер отправил при последнем запросе целевой страницы; используйте их в последующих запросах
`headers`	object	Заголовки ответа целевой страницы после прохождения проверки
`content`	string	HTML-код целевой страницы после прохождения проверки

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

В последующих запросах используйте одновременно возвращённые cookies, возвращённый user_agent и тот же прокси, что был в задаче. cf_clearance привязан к User-Agent и выходному IP: если не совпадает хотя бы одно из трёх, страница проверки появится снова.
По возможности передавайте заголовки из request_headers и используйте TLS-отпечаток, совпадающий с браузерным (например, параметр impersonate в curl_cffi).
У cf_clearance есть срок действия (его задаёт целевой сайт, на некоторых сайтах он достигает 1 часа). В течение этого срока проходить проверку повторно не нужно, но слишком частые запросы могут привести к блокировке IP со стороны Cloudflare.
Если нужно только содержимое страницы, используйте content напрямую, повторно запрашивать страницу не нужно.

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

За ошибки, возвращённые при создании задачи, баллы не списываются; если задача после создания завершилась неудачей или таймаутом, баллы возвращаются автоматически. API возвращает только код ошибки и общее описание, а конкретную причину можно найти в таблице ниже.

Код ошибки	Когда возвращается	Что делать
`ERROR_REQUIRED_FIELDS`	При создании задачи: нет `websiteURL` или `proxy`	Добавьте оба обязательных поля
`ERROR_ILLEGAL_PARAMETERS`	При создании задачи: `websiteURL` не является публичным адресом, начинающимся с `http://` / `https://`, `postData` не объект, `requiredCookies` не массив строк. При запросе результата: через прокси не удаётся разрешить домен целевого адреса	Исправьте параметры; проверьте написание URL и то, что прокси имеет доступ к этому сайту
`ERROR_PROXY_INCORRECT`	При создании задачи: неверный формат прокси, нет порта, используется `https://`-прокси или socks5 с логином и паролем	Исправьте запись по разделу «Требования к прокси» выше; если нужны логин и пароль, используйте http-прокси
`ERROR_PROXY_BANNED`	При создании задачи: прокси — локальный, внутренний или зарезервированный адрес, либо к нему не удавалось подключиться несколько раз за короткое время. При запросе результата: Cloudflare целевого сайта сразу заблокировал IP этого прокси (страницы «Sorry, you have been blocked», «Access denied»)	Смените прокси; чем качественнее IP, тем легче пройти проверку
`ERROR_PROXY_CONNECT_REFUSED`	Не удаётся подключиться к прокси (отказ в соединении, домен прокси не разрешается) либо при открытии страницы через прокси соединение отклонено или сброшено	Проверьте адрес и порт прокси, убедитесь, что он работает и разрешает внешние подключения; если ошибка остаётся, смените прокси
`ERROR_PROXY_CONNECT_TIMEOUT`	Таймаут при подключении к прокси или при открытии страницы через прокси	Используйте более быстрый и стабильный прокси
`ERROR_PROXY_NOT_AUTHORISED`	Неверный логин или пароль прокси	Проверьте логин и пароль в `proxy`; специальные символы нужно закодировать (URL-кодирование)
`ERROR_PROXY_TLS_ERROR`	Ошибка TLS-рукопожатия при открытии страницы через прокси	Убедитесь, что адрес, порт и протокол прокси указаны верно; если ошибка остаётся, смените прокси
`ERROR_CAPTCHA_UNSOLVABLE`	Проверка не пройдена за отведённое время, после прохождения страница всё ещё остаётся страницей проверки, либо не получен cookie, указанный в `requiredCookies`	Сначала смените прокси и повторите; по отдельным сайтам можно обратиться в поддержку
`ERROR_NO_SLOT_AVAILABLE`	При создании задачи: очередь заполнена. При запросе результата: задача слишком долго ждала в очереди и не началась, баллы возвращены	Подождите несколько секунд и создайте задачу заново
`ERROR_TASK_TIMEOUT`	Задача не завершилась за отведённое время	Создайте задачу заново; постоянные таймауты обычно означают, что прокси слишком медленный

Полный список кодов ошибок: Коды ошибок.

См. также

Как определить тип капчи: чем страница проверки Cloudflare отличается от Turnstile
Cloudflare Turnstile