token으로 reCAPTCHA 완료하기

YesCaptcha가 반환하는 gRecaptchaResponse는 웹 페이지에서 캡차를 완료한 뒤 Google이 페이지에 전달하는 결과와 같은 값이에요. 이 값을 받으면 브라우저처럼 대상 웹사이트에 제출해야 해요(Google이나 YesCaptcha에 제출하는 게 아니에요). 웹사이트는 이 값을 Google에 확인한 뒤 통과시켜요. 방법은 두 가지예요. 직접 요청을 보내 제출하거나, 브라우저에서 페이지에 입력한 뒤 제출해요.

동작 원리

일반적인 접속 흐름은 다음과 같아요.

1. 웹 페이지가 reCAPTCHA를 로드하고, 사용자가 인증을 완료해요.
2. Google이 페이지에 token을 주고, 페이지는 이를 g-recaptcha-response 텍스트 상자에 넣어요(또는 콜백 함수에 전달해요).
3. 사용자가 폼을 제출하면 token이 폼과 함께 웹사이트 서버로 전송돼요.
4. 웹사이트 서버가 token을 Google에 확인하고, 통과하면 요청을 허용해요.

YesCaptcha를 사용하면 1, 2단계는 저희가 처리해요. websiteURL과 websiteKey로 작업을 생성해 token을 받은 뒤, 3단계부터 이어서 진행하면 돼요.

주의

token은 일회용이며 약 120초 동안 유효해요. 받은 뒤 60초 이내에 제출하는 것을 권장해요. 만료된 token은 웹사이트에서 받아주지 않아요.

방법 1: 직접 요청으로 제출하기 (권장)

1. 브라우저에서 한 번 정상적으로 진행해요. F12를 눌러 Network 패널을 열고, 캡차를 완료한 뒤 제출해서 폼을 제출하는 요청을 찾아요.
2. 요청의 Payload(또는 Form Data)에서 token을 담은 필드를 찾아요. 보통 g-recaptcha-response이고, token은 03A로 시작해요. 일부 웹사이트는 이름을 바꾸기도 해요. 예를 들면 grecaptcharesponse, captcha가 있어요.
3. 프로그램에서 똑같은 요청을 보내되, 해당 필드의 값을 YesCaptcha가 반환한 token으로 바꿔요. 다른 필드, Cookie, 요청 헤더도 브라우저와 동일해야 해요. 웹사이트가 이들을 함께 검사하는 경우가 많아요.

Google 데모 페이지의 전체 예제예요. 먼저 인식한 뒤, token을 g-recaptcha-response 필드로 데모 페이지에 다시 제출해요.

recaptcha_requests.py

"""Solve reCAPTCHA v2 on Google's demo page and submit the token with plain HTTP (no browser).

Run:  pip install requests
      export YESCAPTCHA_CLIENT_KEY=your_client_key
      python recaptcha_requests.py
Each run creates one NoCaptchaTaskProxyless task (charged per the price list).
"""
import os
import time

import requests

CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
API = "https://api.yescaptcha.com"
WEBSITE_URL = "https://www.google.com/recaptcha/api2/demo"
WEBSITE_KEY = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"


def call(method, payload):
    data = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30).json()
    if data.get("errorId"):
        raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
    return data


def get_token():
    task = {"type": "NoCaptchaTaskProxyless", "websiteURL": WEBSITE_URL, "websiteKey": WEBSITE_KEY}
    task_id = call("createTask", {"task": task})["taskId"]
    for _ in range(36):  # poll every 5 seconds, for up to about 3 minutes
        time.sleep(5)
        result = call("getTaskResult", {"taskId": task_id})
        if result.get("status") == "ready":
            return result["solution"]["gRecaptchaResponse"]
    raise TimeoutError(task_id)


token = get_token()
print("token:", token[:40], "...")

# Submit the token the same way the browser does: the demo form posts the field
# "g-recaptcha-response" back to the page. Check your own site's request in DevTools > Network.
page = requests.post(WEBSITE_URL, data={"g-recaptcha-response": token}, timeout=30)
print("passed" if "Verification Success" in page.text else "not passed", page.status_code)

방법 2: 브라우저에 입력하기 (Selenium 등)

Selenium, Playwright 같은 도구로 실제 브라우저를 조작할 때는 다음과 같이 해요.

1. 페이지에서 data-sitekey를 읽고, 이 값으로 작업을 생성해 token을 받아요.
2. token을 페이지의 g-recaptcha-response 텍스트 상자에 써 넣어요.
3. 페이지에 콜백 함수(data-callback="...")가 설정되어 있으면 token을 전달해 호출해요. 일부 웹사이트는 콜백을 호출해야 제출 버튼이 클릭 가능해져요.
4. 폼을 제출해요.

// Step 2: write the token (run in the page)
document.getElementById('g-recaptcha-response').value = 'TOKEN';
// Step 3: call the callback if there is one, e.g. data-callback="onSuccess"
onSuccess('TOKEN');

페이지에 reCAPTCHA가 여러 개 있으면 텍스트 상자의 id가 g-recaptcha-response-1처럼 될 수 있어요. 이 텍스트 상자를 찾을 수 없으면, 먼저 수동으로 인증을 한 번 완료하고 Elements에서 03A를 검색해 결과가 어디에 들어가는지 확인해 보세요. 콜백 함수를 찾는 방법은 reCAPTCHA 파라미터 찾기를 참고하세요.

전체 예제(Selenium 4)예요.

recaptcha_selenium.py

"""Solve reCAPTCHA v2 on Google's demo page in a real browser with Selenium 4:
get a token from YesCaptcha, put it into the page, then submit the form.

Run:  pip install requests selenium
      export YESCAPTCHA_CLIENT_KEY=your_client_key
      python recaptcha_selenium.py
Each run creates one NoCaptchaTaskProxyless task (charged per the price list).
"""
import os
import time

import requests
from selenium import webdriver
from selenium.webdriver.common.by import By

CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
API = "https://api.yescaptcha.com"
WEBSITE_URL = "https://www.google.com/recaptcha/api2/demo"


def call(method, payload):
    data = requests.post(f"{API}/{method}", json={"clientKey": CLIENT_KEY, **payload}, timeout=30).json()
    if data.get("errorId"):
        raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
    return data


def get_token(website_url, website_key):
    task = {"type": "NoCaptchaTaskProxyless", "websiteURL": website_url, "websiteKey": website_key}
    task_id = call("createTask", {"task": task})["taskId"]
    for _ in range(36):
        time.sleep(5)
        result = call("getTaskResult", {"taskId": task_id})
        if result.get("status") == "ready":
            return result["solution"]["gRecaptchaResponse"]
    raise TimeoutError(task_id)


driver = webdriver.Chrome()  # Selenium 4 downloads a matching chromedriver automatically
try:
    driver.get(WEBSITE_URL)
    site_key = driver.find_element(By.CSS_SELECTOR, "[data-sitekey]").get_attribute("data-sitekey")
    token = get_token(WEBSITE_URL, site_key)

    # Put the token where reCAPTCHA keeps it ...
    driver.execute_script(
        "document.getElementById('g-recaptcha-response').value = arguments[0];", token
    )
    # ... and, if the page uses a callback (data-callback="..."), call it:
    callback = driver.find_element(By.CSS_SELECTOR, "[data-sitekey]").get_attribute("data-callback")
    if callback:
        driver.execute_script(f"window[{callback!r}](arguments[0]);", token)

    driver.find_element(By.ID, "recaptcha-demo-submit").click()
    time.sleep(2)
    print("passed" if "Verification Success" in driver.page_source else "not passed")
finally:
    driver.quit()

reCAPTCHA v3

v3에는 체크박스가 없어요. 웹 페이지가 필요할 때 grecaptcha.execute(사이트 키, {action: '...'})를 호출해 token을 받고, 그 token을 자체 요청에 넣어요(필드 이름은 웹사이트가 정해요. 흔히 g-recaptcha-response, token, recaptchaToken을 써요). 방법은 방법 1과 같아요. Network에서 token이 담긴 요청을 찾아 그대로 보내면 돼요. 작업을 생성할 때 pageAction은 웹 페이지의 action과 일치해야 해요.

제출했는데도 통과하지 않을 때

• token이 만료됐어요. 받은 뒤 최대한 빨리, 60초를 넘기지 말고 제출하세요.
• 웹사이트가 검사하는 필드가 아닌 곳에 제출했거나, 다른 필드나 Cookie가 빠졌어요. 브라우저의 요청과 항목별로 대조해 확인하세요.
• 웹사이트가 IP, User-Agent 등도 함께 검사해요. 자체 프록시를 사용하는 유형(예: NoCaptchaTask)을 쓰고, 제출할 때도 같은 프록시를 거치세요.
• v3 점수가 부족해요. pageAction을 확인하거나 고정 고점수 유형으로 바꾸세요. reCAPTCHA v3를 참고하세요.
• 웹사이트의 위험 탐지가 다른 행동 신호도 확인해요. token 방식의 통과율이 낮으면 이미지 인식으로 브라우저에서 실제로 클릭하거나, 브라우저 확장 프로그램을 사용하세요.