hCaptcha

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

hCaptcha 任务返回一个 token（gRecaptchaResponse），连同返回的 userAgent（有时还有 respKey）一起提交给目标网站即可通过验证。HCaptchaTaskProxyless 每个任务 30 点（0.03 元），自带代理的 HCaptchaTask 每个任务 15 点（0.015 元），都是异步：先 createTask，再每 5 秒 getTaskResult。识别失败、超时自动退点。

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

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

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

适用场景

网页上有 hCaptcha 的“我是人类”复选框，或者弹出 hCaptcha 的图片题。想拿 token 直接提交，用这一页的类型；想自己在浏览器里点图片，用 hCaptcha 图像识别。

hCaptcha 的通过率因网站差异很大，建议先小批量测试。

类型与价格

任务类型	价格	返回方式	说明
`HCaptchaTaskProxyless`	30 点（0.03 元）	异步
`HCaptchaTaskProxylessM1`	30 点（0.03 元）	异步	和 HCaptchaTaskProxyless 参数相同、线路不同，可以互为备用
`HCaptchaTask`	15 点（0.015 元）	异步	自带代理

HCaptchaTaskProxyless 和 HCaptchaTaskProxylessM1 参数相同、线路不同，可以互为备用。
HCaptchaTask 用你自己的代理加载验证码，要传代理字段；目标网站检查访问 IP 时用它。

请求参数

字段	类型	必填	说明
`type`	string	是	任务类型，取值见本页"类型与价格"
`websiteURL`	string	是	出现验证码的网页地址（完整 URL）。填你看到验证码的网站，不要填验证码厂商的域名
`websiteKey`	string	是	hCaptcha 的网站密钥（sitekey），一般是 UUID 格式
`userAgent`	string	否	浏览器 User-Agent，建议填，但只能填 `GET https://api.yescaptcha.com/useragent` 返回的值；提交 token 时用结果里返回的 `userAgent`
`isInvisible`	boolean	否	隐形（invisible）版本时传 true，普通版本不传
`rqdata`	string	否	企业版 hCaptcha 的 rqdata，部分网站需要，一般在加载验证码的请求里找到
`proxyType`	string	HCaptchaTask 必填	代理协议：`http`、`https`、`socks4`、`socks5`
`proxyAddress`	string	HCaptchaTask 必填	代理的 IP 地址或域名。不能填 127.0.0.1、192.168.x.x 这类本机或内网地址，我们的服务器访问不到
`proxyPort`	integer	HCaptchaTask 必填	代理端口
`proxyLogin`	string	否	代理用户名（代理需要认证时）（仅 HCaptchaTask）
`proxyPassword`	string	否	代理密码（代理需要认证时）（仅 HCaptchaTask）

websiteURL 填出现验证码的那个网页，不是 hcaptcha.com。
userAgent 建议填，但只能填 /useragent 返回的值。
rqdata：企业版 hCaptcha（例如部分社交、聊天网站）会要求，一般在加载验证码的请求里能找到。普通网站不传。

参数怎么找，见查找 hCaptcha 参数。

请求示例

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
  }
}

curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2"
  }
}'

# 返回 {"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": "HCaptchaTaskProxyless",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
})
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: "HCaptchaTaskProxyless",
  websiteURL: "https://accounts.hcaptcha.com/demo",
  websiteKey: "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
});
console.log(solution.gRecaptchaResponse);

用自己的代理：

{
  "clientKey": "YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaTask",
    "websiteURL": "https://accounts.hcaptcha.com/demo",
    "websiteKey": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
    "proxyType": "http",
    "proxyAddress": "proxy.example.com",
    "proxyPort": 8080,
    "proxyLogin": "user",
    "proxyPassword": "pass"
  }
}

返回结果

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36",
    "respKey": "E0_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
  }
}

字段	类型	说明
`gRecaptchaResponse`	string	得到的 token，提交给目标网站。一次性使用，约 120 秒内有效，建议 60 秒内用掉
`userAgent`	string	生成 token 时用的 User-Agent。提交 token 时请用这个值，和你传的不同时以它为准
`respKey`	string	部分网站需要和 token 一起提交的值，有就一起提交

提交时：

token 填进网页里 h-captcha-response（以及 g-recaptcha-response，如果有）字段，或者放进目标网站接口要求的字段。
发送提交请求时，User-Agent 用返回的 userAgent。
返回了 respKey 的，按网站的要求一起提交。

处理中时返回 {"errorId": 0, "status": "processing"}，5 秒后再查。出错时按 errorCode 处理，见错误码。

常见问题

通过率为什么不稳定？

hCaptcha 会根据网站的设置、访问的 IP 和浏览器环境判断，通过率因网站而异。确认用了返回的 userAgent；对 IP 敏感的网站用自带代理的 HCaptchaTask，并且提交时也走同一个代理；也可以换 HCaptchaTaskProxylessM1 对比。

token 多久内有效？

一次性使用，约 120 秒内有效，建议拿到后尽快提交。