# reCAPTCHA v2

> 用 YesCaptcha 获取 reCAPTCHA v2（普通版、隐形版、企业版）的 token：任务类型和价格、请求参数、curl/Python/Node.js 示例和返回结果。

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

reCAPTCHA v2 任务返回一个 token（`gRecaptchaResponse`），把它提交给目标网站就能通过验证，不需要点图片。最常用的 `NoCaptchaTaskProxyless` 每个任务 15 点（0.015 元），异步返回：先调用 `createTask` 创建任务，再每 5 秒调用一次 `getTaskResult` 取结果。识别失败、超时的任务自动退点。

- POST `https://api.yescaptcha.com/createTask` (国际节点)
- POST `https://cn.yescaptcha.com/createTask` (国内节点)

请求体是 JSON，用 `clientKey`（账户密钥，在 [yescaptcha.com](https://yescaptcha.com/) 后台复制）鉴权。在哪个节点创建的任务，就到哪个节点查询结果。

## 适用场景

-   网页上有“进行人机身份验证”（I’m not a robot）复选框：普通版。
-   没有复选框，点击提交按钮后才弹出图片题：隐形版，加 `"isInvisible": true`。
-   网页加载的是 `recaptcha/enterprise.js`，或者请求地址里带 `enterprise`：企业版，用名字里带 `Enterprise` 的类型。

不确定是哪一种，看 [判断验证码类型](https://docs.yescaptcha.com/zh/guides/identify-captcha/)。token 方式通过率不理想时，可以改用 [reCAPTCHA v2 图像识别](https://docs.yescaptcha.com/zh/tasks/recaptcha-classification/)：接口告诉你该点哪几张图，由你在浏览器里点击。

## 类型与价格

| 任务类型 | 价格 | 返回方式 | 说明 |
| --- | --- | --- | --- |
| `NoCaptchaTaskProxyless` | 15 点（0.015 元） | 异步 |  |
| `RecaptchaV2TaskProxyless` | 20 点（0.02 元） | 异步 | 和 NoCaptchaTaskProxyless 参数相同、线路不同，可以互为备用 |
| `NoCaptchaTask` | 15 点（0.015 元） | 异步 | 自带代理 |
| `RecaptchaV2EnterpriseTaskProxyless` | 20 点（0.02 元） | 异步 |  |
| `RecaptchaV2EnterpriseTask` | 20 点（0.02 元） | 异步 | 自带代理 |

-   `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 | NoCaptchaTask、RecaptchaV2EnterpriseTask 必填 | 代理协议：`http`、`https`、`socks4`、`socks5` |
| `proxyAddress` | string | NoCaptchaTask、RecaptchaV2EnterpriseTask 必填 | 代理的 IP 地址或域名。不能填 127.0.0.1、192.168.x.x 这类本机或内网地址，我们的服务器访问不到 |
| `proxyPort` | integer | NoCaptchaTask、RecaptchaV2EnterpriseTask 必填 | 代理端口 |
| `proxyLogin` | string | 否 | 代理用户名（代理需要认证时）（仅 NoCaptchaTask、RecaptchaV2EnterpriseTask） |
| `proxyPassword` | string | 否 | 代理密码（代理需要认证时）（仅 NoCaptchaTask、RecaptchaV2EnterpriseTask） |
| `userAgent` | string | 否 | 浏览器 User-Agent。返回结果里如果带了 `userAgent`，提交 token 时要用返回的这个值（仅 NoCaptchaTask、RecaptchaV2EnterpriseTask） |
| `enterprisePayload` | object | 否 | 企业版的附加参数，例如 reCAPTCHA 企业版的 `s` 值：`{"s": "..."}`。网页没有用到时不传（仅 RecaptchaV2EnterpriseTaskProxyless、RecaptchaV2EnterpriseTask） |

`websiteURL` 和 `websiteKey` 怎么找，见 [查找 reCAPTCHA 参数](https://docs.yescaptcha.com/zh/guides/find-recaptcha-parameters/)。

## 请求示例

以 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 秒查询一次、打印 token），运行前把 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-"
  }
}'
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": "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; // 从环境变量读取 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: "NoCaptchaTaskProxyless",
  websiteURL: "https://www.google.com/recaptcha/api2/demo",
  websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
console.log(solution.gRecaptchaResponse);
```

企业版，并且网页向 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" }
```

用它调用 `getTaskResult`。还在处理时返回 `{"errorId": 0, "status": "processing"}`，5 秒后再查；完成时返回：

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `gRecaptchaResponse` | string | 得到的 token，提交给目标网站。一次性使用，约 120 秒内有效，建议 60 秒内用掉 |

任务最长处理约 110 秒，超时返回 `ERROR_TASK_TIMEOUT` 并退点。出错时 `errorId` 为 1，按 `errorCode` 处理，见 [错误码](https://docs.yescaptcha.com/zh/api/errors/)。拿到 token 之后怎么提交，见 [用 token 完成 reCAPTCHA](https://docs.yescaptcha.com/zh/guides/submit-recaptcha-token/)。

## 常见问题

### 为什么同一个网站的 token 有时通过、有时不通过？

能否通过由目标网站判定。网站会给每次验证打分并设置门槛，门槛随时可能调整，所以通过率因网站而异，不是每个 token 都能通过。可以换一个同类的任务类型对比通过率，或者改用 [图像识别](https://docs.yescaptcha.com/zh/tasks/recaptcha-classification/)。

### token 多久内有效？

一次性使用，约 120 秒内有效，建议拿到后 60 秒内提交。有效期由 Google 决定。

### 识别失败扣点吗？

不扣。返回 `ERROR_CAPTCHA_UNSOLVABLE` 或超时的任务自动退点，见 [计费与退点](https://docs.yescaptcha.com/zh/getting-started/billing/)。

## 相关教程

-   [判断验证码类型](https://docs.yescaptcha.com/zh/guides/identify-captcha/)
-   [查找 reCAPTCHA 参数](https://docs.yescaptcha.com/zh/guides/find-recaptcha-parameters/)
-   [用 token 完成 reCAPTCHA](https://docs.yescaptcha.com/zh/guides/submit-recaptcha-token/)
-   [reCAPTCHA v2 图像识别模拟点击（Selenium）](https://docs.yescaptcha.com/zh/guides/recaptcha-click-selenium/)