# reCAPTCHA v2 > YesCaptcha로 reCAPTCHA v2(일반, 인비저블, Enterprise)의 토큰을 받아요. 작업 유형과 가격, 요청 파라미터, curl/Python/Node.js 예제와 반환 결과를 안내해요. Source: https://docs.yescaptcha.com/ko/tasks/recaptcha-v2/ · Last verified: 2026-10-15 > This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/recaptcha-v2/ reCAPTCHA v2 작업은 토큰(`gRecaptchaResponse`)을 반환해요. 이 토큰을 대상 웹사이트에 제출하면 이미지를 클릭하지 않고도 검증을 통과할 수 있어요. 가장 많이 쓰는 `NoCaptchaTaskProxyless`는 작업당 15 포인트 (≈ $2.25 / 1k)이고 비동기로 결과를 반환해요. 먼저 `createTask`로 작업을 만들고, 5초마다 `getTaskResult`를 호출해 결과를 가져와요. 인식에 실패하거나 시간이 초과된 작업은 포인트가 자동으로 환불돼요. - POST `https://api.yescaptcha.com/createTask` (글로벌 엔드포인트) - POST `https://cn.yescaptcha.com/createTask` (중국 엔드포인트) 요청 본문은 JSON이고, `clientKey`로 인증해요. `clientKey`는 [yescaptcha.com](https://yescaptcha.com/) 대시보드에서 복사하세요. 작업을 만든 엔드포인트와 같은 엔드포인트에서 결과를 조회해야 해요. ## 사용 시기 - 웹페이지에 “로봇이 아닙니다”(I’m not a robot) 체크박스가 있어요: 일반 버전이에요. - 체크박스가 없고, 제출 버튼을 클릭한 뒤에야 이미지 문제가 나타나요: 인비저블 버전이에요. `"isInvisible": true`를 추가하세요. - 웹페이지가 `recaptcha/enterprise.js`를 불러오거나 요청 주소에 `enterprise`가 들어 있어요: Enterprise 버전이에요. 이름에 `Enterprise`가 들어간 유형을 사용하세요. 어떤 버전인지 확실하지 않다면 [캡차 유형 확인하기](https://docs.yescaptcha.com/ko/guides/identify-captcha.md)를 참고하세요. 토큰 방식의 통과율이 만족스럽지 않다면 [reCAPTCHA v2 이미지 인식](https://docs.yescaptcha.com/ko/tasks/recaptcha-classification.md)을 사용할 수 있어요. 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 파라미터 찾기](https://docs.yescaptcha.com/ko/guides/find-recaptcha-parameters.md)를 참고하세요. ## 요청 예제 Google 공식 데모 페이지를 예로 들어요: POST https://api.yescaptcha.com/createTask ```json { "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** ```bash 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 ```python 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 ```js 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 ```json { "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 ```json { "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를 반환해요: ```json { "errorId": 0, "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006" } ``` 이 ID로 `getTaskResult`를 호출하세요. 아직 처리 중이면 `{"errorId": 0, "status": "processing"}`가 반환되니 5초 후에 다시 조회하세요. 완료되면 다음과 같이 반환돼요: ```json { "errorId": 0, "status": "ready", "solution": { "gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..." } } ``` | 필드 | 유형 | 설명 | | --- | --- | --- | | `gRecaptchaResponse` | string | 대상 웹사이트에 제출할 토큰이에요. 1회만 사용할 수 있고 약 120초 동안 유효하며, 60초 안에 사용하는 것을 권장해요 | 작업 하나는 최대 약 110초 동안 처리되고, 시간이 초과되면 `ERROR_TASK_TIMEOUT`이 반환되며 포인트가 환불돼요. 오류가 발생하면 `errorId`가 1이 되니 `errorCode`에 따라 처리하세요. 자세한 내용은 [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md)를 참고하세요. 토큰을 받은 뒤 제출하는 방법은 [토큰으로 reCAPTCHA 통과하기](https://docs.yescaptcha.com/ko/guides/submit-recaptcha-token.md)를 참고하세요. > **팁:** 토큰은 일회용이고 약 120초 동안 유효해요. 받은 뒤 60초 안에 제출하는 것을 권장해요. ## 자주 묻는 질문 ### 같은 웹사이트인데 토큰이 통과될 때도 있고 안 될 때도 있는 이유가 뭔가요? 통과 여부는 대상 웹사이트가 판단해요. 웹사이트는 검증할 때마다 점수를 매기고 기준을 설정하는데, 이 기준은 언제든 바뀔 수 있어요. 그래서 통과율은 웹사이트마다 다르고, 모든 토큰이 통과되는 것은 아니에요. 같은 종류의 다른 작업 유형으로 통과율을 비교해 보거나 [이미지 인식](https://docs.yescaptcha.com/ko/tasks/recaptcha-classification.md)으로 바꿔 보세요. ### 토큰은 얼마 동안 유효한가요? 일회용이고 약 120초 동안 유효해요. 받은 뒤 60초 안에 제출하는 것을 권장해요. 유효 기간은 Google이 정해요. ### 인식에 실패하면 포인트가 차감되나요? 차감되지 않아요. `ERROR_CAPTCHA_UNSOLVABLE`을 반환하거나 시간이 초과된 작업은 포인트가 자동으로 환불돼요. 자세한 내용은 [과금과 포인트 환불](https://docs.yescaptcha.com/ko/getting-started/billing.md)을 참고하세요. ## 관련 튜토리얼 - [캡차 유형 확인하기](https://docs.yescaptcha.com/ko/guides/identify-captcha.md) - [reCAPTCHA 파라미터 찾기](https://docs.yescaptcha.com/ko/guides/find-recaptcha-parameters.md) - [토큰으로 reCAPTCHA 통과하기](https://docs.yescaptcha.com/ko/guides/submit-recaptcha-token.md) - [reCAPTCHA v2 이미지 인식으로 클릭 시뮬레이션하기(Selenium)](https://docs.yescaptcha.com/ko/guides/recaptcha-click-selenium.md)