Типы задач

hCaptcha

Эта страница переведена с китайской версии машинным переводом и может содержать ошибки. Приоритет имеет китайская версия.

Я человекhCaptchaКонфиденциальность - Условия

ИллюстрацияhCaptcha: флажок «Я человек». После клика флажок либо сразу отмечается, либо открывается задание с изображениями.

Задача hCaptcha возвращает токен (gRecaptchaResponse). Отправьте его на целевой сайт вместе с возвращённым userAgent (а иногда и respKey), и проверка будет пройдена. HCaptchaTaskProxyless стоит 30 pts (≈ $4.50 / 1k) за задачу, HCaptchaTask с собственным прокси — 15 pts (≈ $2.25 / 1k) за задачу. Обе асинхронные: сначала createTask, затем getTaskResult каждые 5 секунд. При ошибке распознавания или таймауте баллы возвращаются автоматически.

POSThttps://api.yescaptcha.com/createTaskГлобальный endpoint

POSThttps://cn.yescaptcha.com/createTaskEndpoint для Китая

Тело запроса — JSON, авторизация через clientKey. Результат запрашивайте на том же endpoint, где создали задачу.

Когда использовать

На странице есть флажок hCaptcha «Я человек» или появляется задание с картинками hCaptcha. Если нужно получить токен и сразу отправить его, используйте типы с этой страницы. Если хотите сами кликать по картинкам в браузере, см. распознавание изображений hCaptcha.

Типы и цены

Тип задачи	Цена	Режим	Примечания
`HCaptchaTaskProxyless`	$4.50 / 1k; 30 pts/задача · ¥30 / 1k	Асинхронный
`HCaptchaTaskProxylessM1`	$4.50 / 1k; 30 pts/задача · ¥30 / 1k	Асинхронный	Те же параметры, что у HCaptchaTaskProxyless, но другой маршрут; можно использовать любой из них как резервный
`HCaptchaTask`	$2.25 / 1k; 15 pts/задача · ¥15 / 1k	Асинхронный	Свой прокси

Цены в долларах США являются оценочными и рассчитаны по курсу 1 USD ≈ ¥6.67; списание за задачи производится в баллах.

У HCaptchaTaskProxyless и HCaptchaTaskProxylessM1 одинаковые параметры, но разные линии, поэтому их можно использовать как резерв друг для друга.
HCaptchaTask загружает капчу через ваш собственный прокси, поэтому нужно передать поля прокси. Используйте его, когда целевой сайт проверяет IP посетителя.

Параметры запроса

Поле	Тип	Обязательное	Описание
`type`	string	Да	Тип задачи; см. «Типы задач и цены» на этой странице
`websiteURL`	string	Да	Полный URL страницы, на которой показывается капча. Укажите сайт, на котором вы видите капчу, а не домен поставщика капчи
`websiteKey`	string	Да	Ключ сайта hCaptcha (sitekey), обычно в формате UUID
`userAgent`	string	Нет	User-Agent браузера. Рекомендуется указывать, но принимается только значение, возвращаемое `GET https://api.yescaptcha.com/useragent`; отправляйте токен с `userAgent` из результата
`isInvisible`	boolean	Нет	Передайте true для невидимого варианта; в остальных случаях не передавайте
`rqdata`	string	Нет	rqdata для Enterprise-версии hCaptcha; требуется некоторым сайтам, обычно находится в запросе, который загружает капчу
`proxyType`	string	Некоторые типы	Протокол прокси: `http`, `https`, `socks4` или `socks5` (Обязательно для HCaptchaTask)
`proxyAddress`	string	Некоторые типы	IP-адрес или имя хоста прокси. Локальные или частные адреса, например 127.0.0.1 или 192.168.x.x, не подойдут, так как наши серверы не могут до них достучаться (Обязательно для HCaptchaTask)
`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"
  }
}'

# 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);

С собственным прокси:

{
  "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	Токен, который нужно отправить на целевой сайт. Одноразовый, действителен около 120 секунд; используйте его в течение 60 секунд
`userAgent`	string	User-Agent, использованный при получении токена. Используйте это значение при отправке токена, даже если оно отличается от переданного вами
`respKey`	string	Значение, которое некоторые сайты требуют отправлять вместе с токеном; если оно есть, отправьте его

При отправке:

Подставьте токен в поле h-captcha-response на странице (и в g-recaptcha-response, если оно есть) или в поле, которое требует API целевого сайта.
При отправке запроса используйте в качестве User-Agent возвращённый userAgent.
Если вернулся respKey, отправьте его вместе с токеном так, как требует сайт.

Пока задача выполняется, возвращается {"errorId": 0, "status": "processing"}; повторите запрос через 5 секунд. Ошибки обрабатывайте по errorCode, см. Коды ошибок.

Частые вопросы

Почему процент прохождения нестабильный?

hCaptcha оценивает настройки сайта, IP посетителя и окружение браузера, поэтому процент прохождения зависит от сайта. Убедитесь, что используете возвращённый userAgent. Для сайтов, чувствительных к IP, берите HCaptchaTask с собственным прокси и отправляйте токен через тот же прокси. Также можно сравнить результаты с HCaptchaTaskProxylessM1.

Как долго действует токен?

Токен одноразовый и действует около 120 секунд, поэтому отправьте его сразу после получения.