# hCaptcha

> Obtenha tokens do hCaptcha com a YesCaptcha: HCaptchaTaskProxyless, HCaptchaTaskProxylessM1 e HCaptchaTask com proxy próprio, como preencher userAgent e rqdata e como usar o respKey retornado.

Source: https://docs.yescaptcha.com/pt/tasks/hcaptcha/ · Last verified: 2026-10-15

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/tasks/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.

- POST `https://api.yescaptcha.com/createTask` (Endpoint global)
- POST `https://cn.yescaptcha.com/createTask` (Endpoint China)

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](https://docs.yescaptcha.com/pt/tasks/hcaptcha-classification.md).

> **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](https://docs.yescaptcha.com/pt/api/useragent.md).
-   `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](https://docs.yescaptcha.com/pt/guides/find-hcaptcha-parameters.md).

## Exemplo de requisição

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

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

**curl**

```bash
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

```python
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

```js
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

```json
{
  "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

```json
{
  "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](https://docs.yescaptcha.com/pt/api/errors.md).

## 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](https://docs.yescaptcha.com/pt/guides/find-hcaptcha-parameters.md)
-   [Cliques simulados no hCaptcha com reconhecimento de imagem (Selenium)](https://docs.yescaptcha.com/pt/guides/hcaptcha-click-selenium.md)