# reCAPTCHA v3

> 用 YesCaptcha 获取 reCAPTCHA v3（含企业版）的 token：pageAction 怎么填，固定分数 0.7、0.9 的类型，任务类型和价格、参数、示例和返回结果。

Source: https://docs.yescaptcha.com/zh/tasks/recaptcha-v3/ · Last verified: 2026-10-15

reCAPTCHA v3 没有复选框也没有图片，网页在后台给访问者打分。YesCaptcha 返回一个 token（`gRecaptchaResponse`），提交给目标网站即可。`RecaptchaV3TaskProxyless` 每个任务 20 点（0.02 元），异步返回：先 `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/zh/guides/identify-captcha/)。

## 类型与价格

| 任务类型 | 价格 | 返回方式 | 说明 |
| --- | --- | --- | --- |
| `RecaptchaV3TaskProxyless` | 20 点（0.02 元） | 异步 |  |
| `RecaptchaV3TaskProxylessM1` | 25 点（0.025 元） | 异步 |  |
| `RecaptchaV3TaskProxylessM1S7` | 30 点（0.03 元） | 异步 | 固定要求分数 0.7，不需要额外参数 |
| `RecaptchaV3TaskProxylessM1S9` | 35 点（0.035 元） | 异步 | 固定要求分数 0.9，不需要额外参数 |
| `RecaptchaV3EnterpriseTask` | 20 点（0.02 元） | 异步 |  |
| `RecaptchaV3EnterpriseTaskM1` | 25 点（0.025 元） | 异步 |  |

-   `RecaptchaV3TaskProxyless` 和 `RecaptchaV3TaskProxylessM1` 参数相同、线路不同，可以互为备用。
-   目标网站要求的分数较高时，用固定分数的 `RecaptchaV3TaskProxylessM1S7`（0.7）或 `RecaptchaV3TaskProxylessM1S9`（0.9），不需要额外参数。

## 请求参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `type` | string | 是 | 任务类型，取值见本页"类型与价格" |
| `websiteURL` | string | 是 | 出现验证码的网页地址（完整 URL）。填你看到验证码的网站，不要填验证码厂商的域名 |
| `websiteKey` | string | 是 | 网站密钥（sitekey），在网页源码或请求里找，一般固定不变 |
| `pageAction` | string | 否 | reCAPTCHA v3 的 action 值，要和网页里 `grecaptcha.execute` 传的一致，否则得到的 token 可能无效 |

`pageAction` 要和网页调用 `grecaptcha.execute(网站密钥, {action: '...'})` 时传的 `action` 一致，填错了 token 可能被网站拒绝。找法见 [查找 reCAPTCHA 参数](https://docs.yescaptcha.com/zh/guides/find-recaptcha-parameters/)。

## 请求示例

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"
  }
}'
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"]  # 从环境变量读取 clientKey

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):  # 每 5 秒查询一次，最多等约 3 分钟
        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; // 从环境变量读取 clientKey

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++) { // 每 5 秒查询一次，最多等约 3 分钟
    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 | 得到的 token，提交给目标网站。一次性使用，约 120 秒内有效，建议 60 秒内用掉 |

处理中时返回 `{"errorId": 0, "status": "processing"}`，5 秒后再查。出错时按 `errorCode` 处理，见 [错误码](https://docs.yescaptcha.com/zh/api/errors/)。拿到 token 后怎么提交，见 [用 token 完成 reCAPTCHA](https://docs.yescaptcha.com/zh/guides/submit-recaptcha-token/)。

## 常见问题

### 为什么 token 有时不被网站接受？

v3 由目标网站根据分数判断，网站设置的门槛可以随时调整，不是每个 token 都能通过。确认 `pageAction` 正确；网站要求高分时试试 `M1S7`、`M1S9`；也可以对比同类的其他类型。

### 企业版 v3 怎么填？

和普通版一样填 `websiteURL`、`websiteKey`、`pageAction`，类型换成 `RecaptchaV3EnterpriseTask` 或 `RecaptchaV3EnterpriseTaskM1`。

### token 多久内有效？

一次性使用，约 120 秒内有效，建议 60 秒内提交。

## 相关教程

-   [判断验证码类型](https://docs.yescaptcha.com/zh/guides/identify-captcha/)
-   [查找 reCAPTCHA 参数](https://docs.yescaptcha.com/zh/guides/find-recaptcha-parameters/)（含 `pageAction` 的找法）
-   [用 token 完成 reCAPTCHA](https://docs.yescaptcha.com/zh/guides/submit-recaptcha-token/)