# reCAPTCHA v3

> YesCaptcha로 reCAPTCHA v3(엔터프라이즈 포함) 토큰을 받는 방법이에요. pageAction 입력 방법, 고정 점수 0.7·0.9 유형, 작업 유형과 가격, 파라미터, 예시, 반환 결과를 설명해요.

Source: https://docs.yescaptcha.com/ko/tasks/recaptcha-v3/ · 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-v3/

reCAPTCHA v3에는 체크박스도 이미지도 없고, 웹 페이지가 백그라운드에서 방문자에게 점수를 매겨요. YesCaptcha는 대상 사이트에 제출할 수 있는 토큰(`gRecaptchaResponse`)을 반환해요. `RecaptchaV3TaskProxyless`는 작업당 20 포인트 (≈ $3.00 / 1k)이며 비동기로 결과를 반환해요. 먼저 `createTask`를 호출하고, 이후 5초마다 `getTaskResult`를 호출하세요. 인식에 실패하거나 시간이 초과되면 포인트가 자동으로 환불돼요.

- POST `https://api.yescaptcha.com/createTask` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/createTask` (중국 엔드포인트)

요청 본문은 JSON이며 `clientKey`로 인증해요. 작업을 만든 엔드포인트와 같은 엔드포인트에서 결과를 조회하세요.

## 사용 시점

-   페이지 소스에 `grecaptcha.execute(...)`가 있거나 `recaptcha/api.js?render=사이트 키`를 로드하는 경우: 일반 v3예요.
-   `grecaptcha.enterprise.execute(...)`를 호출하거나 `recaptcha/enterprise.js`를 로드하는 경우: 엔터프라이즈 v3예요. `RecaptchaV3EnterpriseTask` 또는 `RecaptchaV3EnterpriseTaskM1`을 사용하세요.

판별 방법은 [캡차 유형 판별하기](https://docs.yescaptcha.com/ko/guides/identify-captcha.md)를 참고하세요.

## 유형과 가격

| 작업 유형 | 가격 | 반환 방식 | 설명 |
| --- | --- | --- | --- |
| `RecaptchaV3TaskProxyless` | $3.00 / 1k; 20 포인트/작업 · ¥20 / 1k | 비동기 |  |
| `RecaptchaV3TaskProxylessM1` | $3.75 / 1k; 25 포인트/작업 · ¥25 / 1k | 비동기 |  |
| `RecaptchaV3TaskProxylessM1S7` | $4.50 / 1k; 30 포인트/작업 · ¥30 / 1k | 비동기 | 점수 0.7을 요청해요. 추가 파라미터는 필요 없어요 |
| `RecaptchaV3TaskProxylessM1S9` | $5.25 / 1k; 35 포인트/작업 · ¥35 / 1k | 비동기 | 점수 0.9를 요청해요. 추가 파라미터는 필요 없어요 |
| `RecaptchaV3EnterpriseTask` | $3.00 / 1k; 20 포인트/작업 · ¥20 / 1k | 비동기 |  |
| `RecaptchaV3EnterpriseTaskM1` | $3.75 / 1k; 25 포인트/작업 · ¥25 / 1k | 비동기 |  |

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

-   `RecaptchaV3TaskProxyless`와 `RecaptchaV3TaskProxylessM1`은 파라미터가 같고 경로만 달라서, 서로 예비로 쓸 수 있어요.
-   대상 사이트가 높은 점수를 요구하면 고정 점수인 `RecaptchaV3TaskProxylessM1S7`(0.7) 또는 `RecaptchaV3TaskProxylessM1S9`(0.9)를 사용하세요. 추가 파라미터는 필요 없어요.

## 요청 파라미터

| 필드 | 유형 | 필수 | 설명 |
| --- | --- | --- | --- |
| `type` | string | 예 | 작업 유형이에요. 이 페이지의 "작업 유형 및 가격"을 참고하세요 |
| `websiteURL` | string | 예 | 캡차가 표시되는 페이지의 전체 URL이에요. 캡차 제공업체의 도메인이 아니라 캡차가 보이는 사이트를 입력하세요 |
| `websiteKey` | string | 예 | 사이트 키(sitekey)예요. 페이지 소스나 네트워크 요청에서 찾을 수 있고, 보통 바뀌지 않아요 |
| `pageAction` | string | 아니요 | reCAPTCHA v3의 action 값이에요. 페이지가 `grecaptcha.execute`에 전달하는 값과 같아야 해요. 다르면 토큰이 거부될 수 있어요 |

`pageAction`은 페이지가 `grecaptcha.execute(사이트 키, {action: '...'})`를 호출할 때 전달하는 `action`과 같아야 해요. 잘못 입력하면 사이트가 토큰을 거부할 수 있어요. 찾는 방법은 [reCAPTCHA 파라미터 찾기](https://docs.yescaptcha.com/ko/guides/find-recaptcha-parameters.md)를 참고하세요.

## 요청 예시

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

```json
{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "RecaptchaV3TaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "SITE_KEY_OF_THE_PAGE",
    "pageAction": "login"
  }
}
```

**curl**

```bash
curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "RecaptchaV3TaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "SITE_KEY_OF_THE_PAGE",
    "pageAction": "login"
  }
}'

# 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": "RecaptchaV3TaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "SITE_KEY_OF_THE_PAGE",
    "pageAction": "login",
})
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: "RecaptchaV3TaskProxyless",
  websiteURL: "https://example.com/login",
  websiteKey: "SITE_KEY_OF_THE_PAGE",
  pageAction: "login",
});
console.log(solution.gRecaptchaResponse);
```

`websiteURL`, `websiteKey`, `pageAction`을 대상 사이트의 값으로 바꾸세요.

## 반환 결과

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

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

처리 중에는 `{"errorId": 0, "status": "processing"}`이 반환돼요. 5초 후에 다시 조회하세요. 오류가 발생하면 `errorCode`에 따라 처리하세요. 자세한 내용은 [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md)를 참고하세요. 토큰을 받은 뒤 제출하는 방법은 [토큰으로 reCAPTCHA 통과하기](https://docs.yescaptcha.com/ko/guides/submit-recaptcha-token.md)를 참고하세요.

## 자주 묻는 질문

### 왜 토큰이 사이트에서 거부될 때가 있나요?

v3는 대상 사이트가 점수를 보고 판단하며, 사이트가 설정한 기준은 언제든 바뀔 수 있어서 모든 토큰이 통과하는 것은 아니에요. `pageAction`이 올바른지 확인하세요. 사이트가 높은 점수를 요구하면 `M1S7`, `M1S9`를 사용해 보세요. 같은 계열의 다른 유형과 비교해 볼 수도 있어요.

### 엔터프라이즈 v3는 어떻게 입력하나요?

일반 버전과 똑같이 `websiteURL`, `websiteKey`, `pageAction`을 입력하고, 유형만 `RecaptchaV3EnterpriseTask` 또는 `RecaptchaV3EnterpriseTaskM1`로 바꾸세요.

### 토큰은 얼마나 오래 유효한가요?

일회용이며 약 120초 동안 유효해요. 60초 이내에 제출하는 것을 권장해요.

## 관련 가이드

-   [캡차 유형 판별하기](https://docs.yescaptcha.com/ko/guides/identify-captcha.md)
-   [reCAPTCHA 파라미터 찾기](https://docs.yescaptcha.com/ko/guides/find-recaptcha-parameters.md) (`pageAction` 찾는 방법 포함)
-   [토큰으로 reCAPTCHA 통과하기](https://docs.yescaptcha.com/ko/guides/submit-recaptcha-token.md)