reCAPTCHA v3

Markdown 版在 ChatGPT 中打开在 Claude 中打开

reCAPTCHA v3 没有复选框也没有图片，网页在后台给访问者打分。YesCaptcha 返回一个 token（gRecaptchaResponse），提交给目标网站即可。RecaptchaV3TaskProxyless 每个任务 20 点（0.02 元），异步返回：先 createTask，再每 5 秒 getTaskResult。识别失败、超时自动退点。

POSThttps://api.yescaptcha.com/createTask国际节点

POSThttps://cn.yescaptcha.com/createTask国内节点

请求体是 JSON，用 clientKey 鉴权。在哪个节点创建的任务，就到哪个节点查询结果。

适用场景

网页源码里有 grecaptcha.execute(...)，或者加载 recaptcha/api.js?render=网站密钥：普通版 v3。
调用的是 grecaptcha.enterprise.execute(...)，或者加载 recaptcha/enterprise.js：企业版 v3，用 RecaptchaV3EnterpriseTask、RecaptchaV3EnterpriseTaskM1。

判断方法见判断验证码类型。

类型与价格

任务类型	价格	返回方式	说明
`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 参数。

请求示例

{
  "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/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"
  }
}'

# 返回 {"errorId":0,"taskId":"..."}，然后每 5 秒查询一次结果：
curl -s https://api.yescaptcha.com/getTaskResult \
  -H 'Content-Type: application/json' \
  -d '{"clientKey": "YOUR_CLIENT_KEY", "taskId": "TASK_ID"}'

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"])

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 换成目标网站的值。

返回结果

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

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

处理中时返回 {"errorId": 0, "status": "processing"}，5 秒后再查。出错时按 errorCode 处理，见错误码。拿到 token 后怎么提交，见用 token 完成 reCAPTCHA。

常见问题

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

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

企业版 v3 怎么填？

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

token 多久内有效？

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