Cloudflare 챌린지 페이지

Cloudflare 챌린지 페이지는 사이트 전체를 Cloudflare가 가로막고 “잠시만 기다리세요…”, “브라우저를 확인하는 중”을 표시하는 확인 페이지예요. YesCaptcha는 사용자가 제공한 프록시로 페이지를 열어 확인을 통과한 뒤, cf_clearance 등 쿠키, 당시 사용한 User-Agent, 요청 헤더, 응답 헤더, 통과 후의 웹페이지 HTML을 반환해요. CloudFlareTaskS2는 작업당 25 포인트 (≈ $3.75 / 1k), CloudFlareTaskS3는 작업당 20 포인트 (≈ $3.00 / 1k)예요. 두 유형은 파라미터, 반환 결과, 효과가 모두 같고 가격만 달라요. 비동기로 결과를 반환하며, 작업 하나는 보통 6~35초가 걸리고 사이트마다 차이가 커요. 인식에 실패하거나 시간이 초과되면 포인트가 자동으로 환불돼요.

POSThttps://api.yescaptcha.com/createTask글로벌 엔드포인트복사

POSThttps://cn.yescaptcha.com/createTask중국 엔드포인트복사

사용 상황

• 페이지 소스에 __cf_chl_rt_tk 또는 cdn-cgi/challenge-platform이 있고 제목이 Just a moment... / “잠시만 기다리세요”예요. 이 경우가 Cloudflare 챌린지 페이지예요. 확인 페이지에서 “사람인지 확인” 체크박스를 눌러야 하는 경우도 이 페이지에서 다뤄요.
• 폼 안에 Cloudflare 인증 위젯만 삽입되어 있다면 Turnstile이므로 이 페이지를 쓰지 않아요.
• requests 같은 라이브러리로 요청하면 403과 “Just a moment…“가 반환되지만 브라우저에서는 바로 열려요. 대부분 TLS 핑거프린트 때문에 차단된 거예요. 브라우저의 TLS 핑거프린트를 흉내 내는 라이브러리(예: curl_cffi)로 바꾸면 요청할 수 있고, 챌린지 통과는 필요 없어요.

유형과 가격

작업 유형	가격	반환 방식	설명
CloudFlareTaskS2	$3.75 / 1k; 25 포인트/작업 · ¥25 / 1k	비동기	자체 프록시
CloudFlareTaskS3	$3.00 / 1k; 20 포인트/작업 · ¥20 / 1k	비동기	자체 프록시

미국 달러 가격은 US$1 ≈ ¥6.67 기준의 추정치이며, 작업은 포인트로 차감돼요.

요청 파라미터

필드	유형	필수	설명
type	string	예	작업 유형이에요. 이 페이지의 "작업 유형 및 가격"을 참고하세요
websiteURL	string	예	챌린지에 막힌 페이지의 전체 URL이에요. http:// 또는 https://로 시작하는 공개 URL이어야 해요. 사설 IP 주소와 localhost 같은 로컬 또는 내부 호스트 이름은 거부돼요
proxy	string	예	문자열 하나로 된 프록시예요: http://user:[email protected]:8080(HTTP 프록시, 인증 정보는 선택) 또는 socks5://proxy.example.com:1080(인증 정보 없음). https:// 프록시와 인증 정보가 있는 SOCKS5는 지원하지 않고, 로컬 또는 사설 주소는 거부돼요. 대상 페이지에 대한 모든 요청이 이 프록시를 통해 전송돼요
userAgent	string	아니요	보통은 생략하세요. Linux 데스크톱 Chrome의 User-Agent만 사용되고, 그 외(Windows, macOS, 모바일, 다른 브라우저)는 무시돼요. 이후 요청에는 항상 결과의 user_agent를 사용하세요
waitLoad	boolean	아니요	기본값은 false예요. true로 설정하면 검증을 통과한 뒤 페이지의 네트워크 활동이 잠잠해질 때까지 기다린 다음 반환해요. 그래서 content에 동적으로 불러온 내용이 더 많이 포함되지만 몇 초 더 걸려요
requiredCookies	array	아니요	반드시 가져와야 하는 쿠키 이름 목록이에요. 문자열 배열로 전달하세요. 예: ["cf_clearance"]. 설정하면 모두 가져왔을 때만 성공해요. 하나라도 가져오지 못하면 ERROR_CAPTCHA_UNSOLVABLE을 반환하고 포인트가 환불돼요. 생략하면 cf_clearance를 가져오려고 시도하지만, 다른 쿠키만 가져와도 성공으로 처리되어 포인트가 차감돼요. cf_clearance가 필요하면 반드시 명시적으로 전달하세요
blockImage	boolean	아니요	true로 설정하면 대상 페이지의 이미지를 불러오지 않아요(Cloudflare 검증 자체에 필요한 이미지는 제외). 프록시 트래픽을 절약할 수 있어요
postData	object	아니요	설정하면 일반 HTML 폼 POST처럼 websiteURL로 제출돼요(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 반환

작업을 만들 때 바로 검사해요

URL이나 프록시가 규칙에 맞지 않으면 createTask가 바로 오류를 반환하고 포인트는 차감되지 않아요. 같은 프록시가 짧은 시간에 여러 번 연결되지 않으면, 이후 한동안은 그 프록시로 작업을 만들 때도 바로 ERROR_PROXY_BANNED가 반환돼요. 프록시를 바꾸거나 잠시 후 다시 시도하세요.

User-Agent

보통은 userAgent를 보내지 않아요. YesCaptcha는 Linux 데스크톱 버전 Chrome으로 확인을 통과해요. 같은 Linux 데스크톱 버전 Chrome의 User-Agent만 적용되고, 그 밖의 것(Windows, macOS, 모바일, 다른 브라우저)은 무시해요. 실측 결과 브라우저의 실제 환경과 User-Agent가 맞지 않으면 Cloudflare 확인을 통과하지 못했어요. 이후 요청에는 항상 결과의 user_agent를 쓰세요.

요청 예시

POST https://api.yescaptcha.com/createTask

{
  "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를 받지 못했을 때 작업이 실패하고 포인트가 환불돼요. 보내지 않으면 cf_clearance 없이 다른 쿠키만 받아도 성공으로 처리되어 포인트가 차감돼요.
• 폼을 제출해야 하면 postData를 추가하세요. 예: {"name": "hi"}. websiteURL로 POST 폼 방식으로 제출돼요.

작업을 만든 뒤에는 5초마다 getTaskResult를 호출하세요. 흐름은 다른 비동기 작업과 같아요. 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>..."
  }
}

위의 쿠키 값과 요청 헤더는 예시예요. 실제 값은 반환된 결과를 따르세요.

필드	유형	설명
cookies	object	검증을 통과한 뒤 브라우저에 있는 모든 쿠키예요(이름-값 객체). 보통 cf_clearance가 포함돼요. requiredCookies를 보냈다면 그 쿠키가 모두 포함돼요. 반환된 user_agent, 작업을 만들 때 사용한 프록시와 함께 사용하세요
user_agent	string	검증을 통과할 때 브라우저가 실제로 사용한 User-Agent예요(Linux 데스크톱 Chrome). cf_clearance가 이 값에 연결되어 있으므로 이후 모든 요청에 이 값을 사용해야 해요
request_headers	object	브라우저가 대상 웹페이지를 마지막으로 요청할 때 보낸 요청 헤더예요. 이후 요청에도 같은 헤더를 사용하는 것을 권장해요
headers	object	검증을 통과한 뒤 받은 대상 웹페이지의 응답 헤더예요
content	string	검증을 통과한 뒤 받은 대상 웹페이지의 HTML 소스예요

결과 사용 방법

1. 이후 요청에는 반환된 cookies, 반환된 user_agent, 작업을 만들 때 쓴 같은 프록시를 모두 함께 쓰세요. cf_clearance는 User-Agent, 출구 IP에 묶여 있어서 셋 중 하나라도 다르면 챌린지 페이지가 다시 나타나요.
2. 요청 헤더도 가능하면 request_headers대로 보내고, 브라우저와 같은 TLS 핑거프린트를 쓰세요(예: curl_cffi의 impersonate 파라미터).
3. cf_clearance에는 유효 기간이 있어요(대상 사이트가 설정하며, 길면 1시간까지 가는 경우도 있어요). 유효 기간 안에는 챌린지를 다시 통과할 필요가 없어요. 다만 요청 빈도가 너무 높으면 Cloudflare가 IP를 차단할 수 있어요.
4. 웹페이지 내용만 필요하면 content를 그대로 쓰면 돼요. 다시 요청할 필요가 없어요.

자주 발생하는 오류

작업을 만들 때 반환된 오류는 포인트가 차감되지 않아요. 작업을 만든 뒤 실패하거나 시간이 초과되면 포인트가 자동으로 환불돼요. 인터페이스는 오류 코드와 일반적인 설명만 반환하므로, 구체적인 원인은 아래 표에서 확인하세요.

오류 코드	반환되는 경우	해결 방법
ERROR_REQUIRED_FIELDS	작업 생성 시: websiteURL 또는 proxy가 없음	필수 필드 두 개를 모두 채우세요
ERROR_ILLEGAL_PARAMETERS	작업 생성 시: websiteURL이 http:// / https://로 시작하는 공개 URL이 아님, postData가 객체가 아님, requiredCookies가 문자열 배열이 아님. 결과 조회 시: 프록시를 통해 대상 URL의 도메인을 확인할 수 없음	파라미터를 고치세요. 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	제한 시간 안에 확인을 통과하지 못했거나, 통과 후에도 챌린지 페이지에 머물러 있거나, requiredCookies에 지정한 쿠키를 받지 못함	먼저 프록시를 바꿔서 다시 시도하세요. 일부 사이트는 고객 지원에 문의하세요
ERROR_NO_SLOT_AVAILABLE	작업 생성 시: 대기열이 가득 참. 결과 조회 시: 대기 시간이 너무 길어 시작하지 못했고 포인트가 환불됨	몇 초 기다린 뒤 작업을 다시 만드세요
ERROR_TASK_TIMEOUT	작업이 제한 시간 안에 완료되지 않음	작업을 다시 만드세요. 시간 초과가 계속되면 대개 프록시가 너무 느린 거예요

전체 오류 코드는 오류 코드를 참고하세요.

관련 문서

• 캡차 유형 판별: Cloudflare 챌린지 페이지와 Turnstile의 차이
• Cloudflare Turnstile