hCaptcha

Uma tarefa de hCaptcha retorna um token (gRecaptchaResponse). Envie-o ao site de destino junto com o userAgent retornado (e com o respKey, quando houver) para passar na verificação. HCaptchaTaskProxyless custa 30 pontos (≈ US$4.50 / 1k) por tarefa e HCaptchaTask (com proxy próprio) custa 15 pontos (≈ US$2.25 / 1k) por tarefa; ambas são assíncronas: createTask e, depois, getTaskResult a cada 5 segundos. Tarefas com falha ou que expiram têm os pontos reembolsados automaticamente.

POSThttps://api.yescaptcha.com/createTaskEndpoint globalCopiar

POSThttps://cn.yescaptcha.com/createTaskEndpoint ChinaCopiar

O corpo da requisição é JSON, autenticado com a clientKey. Consulte o resultado no mesmo endpoint em que criou a tarefa.

Quando usar

A página exibe a caixa de seleção “Sou humano” do hCaptcha ou um desafio de imagens do hCaptcha. Para obter um token e enviá-lo diretamente, use os tipos desta página; para clicar nas imagens você mesmo no navegador, use reconhecimento de imagem do hCaptcha.

Nota

A taxa de aprovação do hCaptcha varia muito de site para site; teste primeiro com um lote pequeno.

Tipos e preços

Tipo de tarefa	Preço	Modo	Observações
HCaptchaTaskProxyless	US$4.50 / 1k; 30 pontos/tarefa · ¥30 / 1k	Assíncrono
HCaptchaTaskProxylessM1	US$4.50 / 1k; 30 pontos/tarefa · ¥30 / 1k	Assíncrono	Mesmos parâmetros de HCaptchaTaskProxyless, mas em outra rota; use qualquer um como alternativa
HCaptchaTask	US$2.25 / 1k; 15 pontos/tarefa · ¥15 / 1k	Assíncrono	Proxy próprio

Os preços em dólares americanos são estimativas com base em US$1 ≈ ¥6.67; as tarefas são cobradas em pontos.

• HCaptchaTaskProxyless e HCaptchaTaskProxylessM1 têm os mesmos parâmetros, mas usam rotas diferentes; um pode servir de reserva para o outro.
• HCaptchaTask carrega o captcha pelo seu próprio proxy e exige os campos de proxy; use-o quando o site verifica o IP de acesso.

Parâmetros da requisição

Campo	Tipo	Obrigatório	Descrição
type	string	Sim	Tipo de tarefa; veja "Tipos de tarefa e preços" nesta página
websiteURL	string	Sim	URL completa da página que exibe o captcha. Use o site em que você vê o captcha, não o domínio do fornecedor do captcha
websiteKey	string	Sim	A chave do site (sitekey) do hCaptcha, normalmente um UUID
userAgent	string	Não	User-Agent do navegador. Recomendado, mas apenas o valor retornado por GET https://api.yescaptcha.com/useragent é aceito; envie o token com o userAgent do resultado
isInvisible	boolean	Não	Defina como true para a variante invisível; caso contrário, omita
rqdata	string	Não	rqdata do hCaptcha Enterprise; exigido por alguns sites e normalmente encontrado na requisição que carrega o captcha
proxyType	string	Alguns tipos	Protocolo do proxy: http, https, socks4 ou socks5 (Obrigatório para HCaptchaTask)
proxyAddress	string	Alguns tipos	Endereço IP ou nome de host do proxy. Endereços locais ou privados, como 127.0.0.1 ou 192.168.x.x, não funcionam porque nossos servidores não conseguem acessá-los (Obrigatório para HCaptchaTask)
proxyPort	integer	Alguns tipos	Porta do proxy (Obrigatório para HCaptchaTask)
proxyLogin	string	Não	Nome de usuário do proxy, se o proxy exigir autenticação (somente HCaptchaTask)
proxyPassword	string	Não	Senha do proxy, se o proxy exigir autenticação (somente HCaptchaTask)

• websiteURL é a página em que o captcha aparece, não hcaptcha.com.
• userAgent é recomendado, mas só aceita o valor retornado por /useragent.
• rqdata: exigido por sites que usam o hCaptcha Enterprise (por exemplo, alguns sites sociais e de chat); geralmente é encontrado na requisição que carrega o captcha. Em sites comuns, não envie.

Para saber como encontrar os parâmetros, veja Encontrar os parâmetros do hCaptcha.

Exemplo de requisição

POST https://api.yescaptcha.com/createTask

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

curl

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

Python

solve.py

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

Node.js

solve.mjs

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

Com proxy próprio:

POST https://api.yescaptcha.com/createTask

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

Resultado

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

Campo	Tipo	Descrição
gRecaptchaResponse	string	O token a ser enviado ao site de destino. Uso único, válido por cerca de 120 segundos; use-o em até 60 segundos
userAgent	string	O User-Agent usado para obter o token. Use este valor ao enviar o token, mesmo que seja diferente do que você enviou
respKey	string	Um valor que alguns sites exigem junto com o token; envie-o, se estiver presente

Para enviar:

1. Coloque o token no campo h-captcha-response da página (e em g-recaptcha-response, se existir), ou no campo que a API do site exigir.
2. Ao enviar a requisição, use como User-Agent o userAgent retornado.
3. Se um respKey foi retornado, envie-o também, conforme a exigência do site.

Enquanto a tarefa está em processamento, a resposta é {"errorId": 0, "status": "processing"}; consulte novamente após 5 segundos. Em caso de erro, trate-o pelo errorCode, conforme Códigos de erro.

Perguntas frequentes

Por que a taxa de aprovação é instável?

O hCaptcha decide com base nas configurações do site, no IP de acesso e no ambiente do navegador, então a taxa de aprovação varia conforme o site. Confirme que está usando o userAgent retornado; em sites sensíveis ao IP, use HCaptchaTask com proxy próprio e faça o envio pelo mesmo proxy; também é possível comparar com HCaptchaTaskProxylessM1.

Por quanto tempo o token é válido?

É de uso único e válido por cerca de 120 segundos. Envie-o o quanto antes.

Tutoriais relacionados

• Encontrar os parâmetros do hCaptcha
• Cliques simulados no hCaptcha com reconhecimento de imagem (Selenium)