hCaptcha

Markdown Open in ChatGPT Open in Claude

An hCaptcha task returns a token (gRecaptchaResponse). Submit it to the target site together with the returned userAgent (and respKey, when present) to pass the check. HCaptchaTaskProxyless costs 30 points (¥0.03) per task and HCaptchaTask (your own proxy) costs 15 points (¥0.015); both are asynchronous: createTask, then getTaskResult every 5 seconds. Failed and timed-out tasks are refunded automatically.

POSThttps://api.yescaptcha.com/createTaskGlobal endpoint

POSThttps://cn.yescaptcha.com/createTaskChina endpoint

The request body is JSON authenticated with your clientKey. Query results on the same endpoint you created the task on.

When to use

The page shows an hCaptcha “I am human” checkbox or an hCaptcha image challenge. Use the types on this page to get a token; to click the images yourself in a browser, use hCaptcha image recognition.

hCaptcha pass rates vary a lot between sites; test with a small batch first.

Task types and pricing

Task type	Price	Mode	Notes
`HCaptchaTaskProxyless`	30 points (¥0.03)	Asynchronous
`HCaptchaTaskProxylessM1`	30 points (¥0.03)	Asynchronous	Same parameters as HCaptchaTaskProxyless on a different route; use either as a fallback
`HCaptchaTask`	15 points (¥0.015)	Asynchronous	Own proxy

HCaptchaTaskProxyless and HCaptchaTaskProxylessM1 take the same parameters on different routes; use either as a fallback for the other.
HCaptchaTask loads the captcha through your own proxy and needs the proxy fields; use it when the site checks the visitor’s IP.

Request parameters

Field	Type	Required	Description
`type`	string	Yes	Task type; see "Task types and pricing" on this page
`websiteURL`	string	Yes	Full URL of the page that shows the captcha. Use the site you see the captcha on, not the captcha vendor's domain
`websiteKey`	string	Yes	The hCaptcha site key (sitekey), usually a UUID
`userAgent`	string	No	Browser User-Agent. Recommended, but only the value returned by `GET https://api.yescaptcha.com/useragent` is accepted; submit the token with the `userAgent` from the result
`isInvisible`	boolean	No	Set to true for the invisible variant; omit otherwise
`rqdata`	string	No	rqdata for enterprise hCaptcha; required by some sites and usually found in the request that loads the captcha
`proxyType`	string	Required for HCaptchaTask	Proxy protocol: `http`, `https`, `socks4` or `socks5`
`proxyAddress`	string	Required for HCaptchaTask	Proxy IP address or hostname. Local or private addresses such as 127.0.0.1 or 192.168.x.x will not work because our servers cannot reach them
`proxyPort`	integer	Required for HCaptchaTask	Proxy port
`proxyLogin`	string	No	Proxy username, if the proxy requires authentication (HCaptchaTask only)
`proxyPassword`	string	No	Proxy password, if the proxy requires authentication (HCaptchaTask only)

websiteURL is the page that shows the captcha, not hcaptcha.com.
userAgent is recommended, but only the value returned by /useragent is accepted.
rqdata: required by sites using hCaptcha Enterprise (some social and chat sites) and usually found in the request that loads the captcha. Omit it for ordinary sites.

How to find them: Find hCaptcha parameters.

Request example

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

# 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"}'

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

With your own proxy:

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

Result

{
  "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..."
  }
}

Field	Type	Description
`gRecaptchaResponse`	string	The token to submit to the target site. Single use, valid for about 120 seconds; use it within 60 seconds
`userAgent`	string	The User-Agent used to obtain the token. Use this value when you submit the token, even if it differs from the one you sent
`respKey`	string	A value some sites require together with the token; submit it if present

To submit:

Put the token in the page’s h-captcha-response field (and g-recaptcha-response, if present), or in whatever field the site’s API expects.
Send the submission with the returned userAgent as the User-Agent.
If a respKey was returned, submit it too as the site requires.

While in progress you get {"errorId": 0, "status": "processing"}; check again 5 seconds later. Handle errors by errorCode as described in Error codes.

FAQ

Why is the pass rate inconsistent?

hCaptcha decides based on the site’s settings, the visitor’s IP and browser environment, so pass rates vary by site. Use the returned userAgent; for IP-sensitive sites, use HCaptchaTask with your own proxy and submit through the same proxy; or compare with HCaptchaTaskProxylessM1.

How long is a token valid?

Single use, valid for about 120 seconds. Submit it as soon as possible.