reCAPTCHA v2

reCAPTCHA v2 작업은 토큰(gRecaptchaResponse)을 반환해요. 이 토큰을 대상 웹사이트에 제출하면 이미지를 클릭하지 않고도 검증을 통과할 수 있어요. 가장 많이 쓰는 NoCaptchaTaskProxyless는 작업당 15 포인트 (≈ $2.25 / 1k)이고 비동기로 결과를 반환해요. 먼저 createTask로 작업을 만들고, 5초마다 getTaskResult를 호출해 결과를 가져와요. 인식에 실패하거나 시간이 초과된 작업은 포인트가 자동으로 환불돼요.

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

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

요청 본문은 JSON이고, clientKey로 인증해요. clientKey는 yescaptcha.com 대시보드에서 복사하세요. 작업을 만든 엔드포인트와 같은 엔드포인트에서 결과를 조회해야 해요.

사용 시기

• 웹페이지에 “로봇이 아닙니다”(I’m not a robot) 체크박스가 있어요: 일반 버전이에요.
• 체크박스가 없고, 제출 버튼을 클릭한 뒤에야 이미지 문제가 나타나요: 인비저블 버전이에요. "isInvisible": true를 추가하세요.
• 웹페이지가 recaptcha/enterprise.js를 불러오거나 요청 주소에 enterprise가 들어 있어요: Enterprise 버전이에요. 이름에 Enterprise가 들어간 유형을 사용하세요.

어떤 버전인지 확실하지 않다면 캡차 유형 확인하기를 참고하세요. 토큰 방식의 통과율이 만족스럽지 않다면 reCAPTCHA v2 이미지 인식을 사용할 수 있어요. API가 어떤 이미지를 클릭해야 하는지 알려 주면, 브라우저에서 직접 클릭해요.

유형과 가격

작업 유형	가격	반환 방식	설명
NoCaptchaTaskProxyless	$2.25 / 1k; 15 포인트/작업 · ¥15 / 1k	비동기
RecaptchaV2TaskProxyless	$3.00 / 1k; 20 포인트/작업 · ¥20 / 1k	비동기	NoCaptchaTaskProxyless와 파라미터는 같고 경로만 달라요. 서로 대체용으로 사용할 수 있어요
NoCaptchaTask	$2.25 / 1k; 15 포인트/작업 · ¥15 / 1k	비동기	자체 프록시
RecaptchaV2EnterpriseTaskProxyless	$3.00 / 1k; 20 포인트/작업 · ¥20 / 1k	비동기
RecaptchaV2EnterpriseTask	$3.00 / 1k; 20 포인트/작업 · ¥20 / 1k	비동기	자체 프록시

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

• NoCaptchaTaskProxyless와 RecaptchaV2TaskProxyless는 파라미터가 같고 경로만 달라요. 하나의 통과율이 만족스럽지 않다면 다른 하나를 사용해 보세요.
• 이름에 Proxyless가 없는 유형(NoCaptchaTask, RecaptchaV2EnterpriseTask)은 직접 준비한 프록시로 캡차를 불러와요. proxyType, proxyAddress, proxyPort 등의 필드를 전달해야 해요. 대상 웹사이트가 접속 IP를 확인할 때 사용하세요.

요청 파라미터

createTask의 task 객체:

필드	유형	필수	설명
type	string	예	작업 유형이에요. 이 페이지의 "작업 유형 및 가격"을 참고하세요
websiteURL	string	예	캡차가 표시되는 페이지의 전체 URL이에요. 캡차 제공업체의 도메인이 아니라 캡차가 보이는 사이트를 입력하세요
websiteKey	string	예	사이트 키(sitekey)예요. 페이지 소스나 네트워크 요청에서 찾을 수 있고, 보통 바뀌지 않아요
isInvisible	boolean	아니요	보이지 않는(invisible) 버전이면 true로 설정하세요. 그렇지 않으면 생략하세요
proxyType	string	일부 유형	프록시 프로토콜이에요: http, https, socks4, socks5 (NoCaptchaTask, RecaptchaV2EnterpriseTask에서 필수)
proxyAddress	string	일부 유형	프록시 IP 주소 또는 호스트 이름이에요. 127.0.0.1이나 192.168.x.x 같은 로컬 또는 사설 주소는 저희 서버가 접근할 수 없어서 사용할 수 없어요 (NoCaptchaTask, RecaptchaV2EnterpriseTask에서 필수)
proxyPort	integer	일부 유형	프록시 포트 (NoCaptchaTask, RecaptchaV2EnterpriseTask에서 필수)
proxyLogin	string	아니요	프록시 사용자 이름(프록시에 인증이 필요한 경우) (NoCaptchaTask, RecaptchaV2EnterpriseTask 전용)
proxyPassword	string	아니요	프록시 비밀번호(프록시에 인증이 필요한 경우) (NoCaptchaTask, RecaptchaV2EnterpriseTask 전용)
userAgent	string	아니요	브라우저 User-Agent예요. 결과에 userAgent가 있으면 토큰을 제출할 때 그 값을 사용하세요 (NoCaptchaTask, RecaptchaV2EnterpriseTask 전용)
enterprisePayload	object	아니요	Enterprise 버전의 추가 파라미터예요. 예를 들어 reCAPTCHA Enterprise의 s 값은 {"s": "..."} 형식이에요. 페이지에서 사용하지 않으면 생략하세요 (RecaptchaV2EnterpriseTaskProxyless, RecaptchaV2EnterpriseTask 전용)

websiteURL과 websiteKey를 찾는 방법은 reCAPTCHA 파라미터 찾기를 참고하세요.

요청 예제

Google 공식 데모 페이지를 예로 들어요:

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

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "NoCaptchaTaskProxyless",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
  }
}

작업 생성, 5초마다 조회, 토큰 출력까지 포함한 전체 코드예요. 실행하기 전에 ClientKey를 환경 변수 YESCAPTCHA_CLIENT_KEY에 넣으세요:

curl

curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "NoCaptchaTaskProxyless",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
  }
}'

# Returns {"errorId":0,"taskId":"..."}; then poll every 5 seconds:
curl -s https://api.yescaptcha.com/getTaskResult \
  -H 'Content-Type: application/json' \
  -d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'

Python

solve.py

import os
import time

import requests

API = "https://api.yescaptcha.com"
CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]  # Read the clientKey from an environment variable


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


def solve(task):
    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"]
    raise TimeoutError(task_id)


solution = solve({
    "type": "NoCaptchaTaskProxyless",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
})
print(solution["gRecaptchaResponse"])

Node.js

solve.mjs

const API = 'https://api.yescaptcha.com';
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY; // Read the clientKey from an environment variable

async function call(method, payload) {
  const res = await fetch(`${API}/${method}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ clientKey: CLIENT_KEY, ...payload }),
  });
  const data = await res.json();
  if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
  return data;
}

async function solve(task) {
  const { taskId } = await call('createTask', { task });
  for (let i = 0; i < 36; i++) { // Poll every 5 seconds, for up to about 3 minutes
    await new Promise((r) => setTimeout(r, 5000));
    const result = await call('getTaskResult', { taskId });
    if (result.status === 'ready') return result.solution;
  }
  throw new Error(`timeout: ${taskId}`);
}

const solution = await solve({
  type: "NoCaptchaTaskProxyless",
  websiteURL: "https://www.google.com/recaptcha/api2/demo",
  websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
console.log(solution.gRecaptchaResponse);

Enterprise 버전이고 웹페이지가 reCAPTCHA에 s 값을 전달한다면 enterprisePayload에 넣으세요:

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

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "RecaptchaV2EnterpriseTaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "SITE_KEY_OF_THE_PAGE",
    "enterprisePayload": {
      "s": "S_VALUE_FROM_THE_PAGE"
    }
  }
}

직접 준비한 프록시를 사용하는 경우:

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

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "NoCaptchaTask",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    "proxyType": "http",
    "proxyAddress": "proxy.example.com",
    "proxyPort": 8080,
    "proxyLogin": "user",
    "proxyPassword": "pass"
  }
}

반환 결과

createTask는 작업 ID를 반환해요:

{
  "errorId": 0,
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}

이 ID로 getTaskResult를 호출하세요. 아직 처리 중이면 {"errorId": 0, "status": "processing"}가 반환되니 5초 후에 다시 조회하세요. 완료되면 다음과 같이 반환돼요:

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
  }
}

필드	유형	설명
gRecaptchaResponse	string	대상 웹사이트에 제출할 토큰이에요. 1회만 사용할 수 있고 약 120초 동안 유효하며, 60초 안에 사용하는 것을 권장해요

작업 하나는 최대 약 110초 동안 처리되고, 시간이 초과되면 ERROR_TASK_TIMEOUT이 반환되며 포인트가 환불돼요. 오류가 발생하면 errorId가 1이 되니 errorCode에 따라 처리하세요. 자세한 내용은 오류 코드를 참고하세요. 토큰을 받은 뒤 제출하는 방법은 토큰으로 reCAPTCHA 통과하기를 참고하세요.

팁

토큰은 일회용이고 약 120초 동안 유효해요. 받은 뒤 60초 안에 제출하는 것을 권장해요.

자주 묻는 질문

같은 웹사이트인데 토큰이 통과될 때도 있고 안 될 때도 있는 이유가 뭔가요?

통과 여부는 대상 웹사이트가 판단해요. 웹사이트는 검증할 때마다 점수를 매기고 기준을 설정하는데, 이 기준은 언제든 바뀔 수 있어요. 그래서 통과율은 웹사이트마다 다르고, 모든 토큰이 통과되는 것은 아니에요. 같은 종류의 다른 작업 유형으로 통과율을 비교해 보거나 이미지 인식으로 바꿔 보세요.

토큰은 얼마 동안 유효한가요?

일회용이고 약 120초 동안 유효해요. 받은 뒤 60초 안에 제출하는 것을 권장해요. 유효 기간은 Google이 정해요.

인식에 실패하면 포인트가 차감되나요?

차감되지 않아요. ERROR_CAPTCHA_UNSOLVABLE을 반환하거나 시간이 초과된 작업은 포인트가 자동으로 환불돼요. 자세한 내용은 과금과 포인트 환불을 참고하세요.

관련 튜토리얼

• 캡차 유형 확인하기
• reCAPTCHA 파라미터 찾기
• 토큰으로 reCAPTCHA 통과하기
• reCAPTCHA v2 이미지 인식으로 클릭 시뮬레이션하기(Selenium)