# hCaptcha

> Obtén tokens de hCaptcha con YesCaptcha: HCaptchaTaskProxyless, HCaptchaTaskProxylessM1 y HCaptchaTask con tu propio proxy, cómo rellenar userAgent y rqdata, y cómo usar el respKey devuelto.

Source: https://docs.yescaptcha.com/es/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/

Una tarea de hCaptcha devuelve un token (`gRecaptchaResponse`). Envíalo al sitio de destino junto con el `userAgent` devuelto (y el `respKey`, cuando exista) para superar la verificación. `HCaptchaTaskProxyless` cuesta 30 puntos (≈ $4.50 / 1k) por tarea y `HCaptchaTask` (con tu propio proxy) cuesta 15 puntos (≈ $2.25 / 1k) por tarea. Ambos son asíncronos: primero `createTask` y después `getTaskResult` cada 5 segundos. Si el reconocimiento falla o se agota el tiempo, los puntos se reembolsan automáticamente.

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

El cuerpo de la solicitud es JSON y se autentica con tu `clientKey`. Consulta el resultado en el mismo endpoint en el que creaste la tarea.

## Cuándo usarlo

La página muestra la casilla “Soy humano” de hCaptcha o aparece un desafío de imágenes de hCaptcha. Si quieres obtener un token y enviarlo directamente, usa los tipos de esta página; si prefieres hacer clic en las imágenes tú mismo en el navegador, usa [reconocimiento de imágenes de hCaptcha](https://docs.yescaptcha.com/es/tasks/hcaptcha-classification.md).

> **Nota:** La tasa de éxito de hCaptcha varía mucho entre sitios; te recomendamos probar primero con un lote pequeño.

## Tipos y precios

| Tipo de tarea | Precio | Modo | Notas |
| --- | --- | --- | --- |
| `HCaptchaTaskProxyless` | $4.50 / 1k; 30 puntos/tarea · ¥30 / 1k | Asíncrono |  |
| `HCaptchaTaskProxylessM1` | $4.50 / 1k; 30 puntos/tarea · ¥30 / 1k | Asíncrono | Mismos parámetros que HCaptchaTaskProxyless en una ruta distinta; puedes usar cualquiera de los dos como respaldo |
| `HCaptchaTask` | $2.25 / 1k; 15 puntos/tarea · ¥15 / 1k | Asíncrono | Proxy propio |

Los precios en dólares son estimaciones con US$1 ≈ ¥6.67; las tareas se cobran en puntos.

-   `HCaptchaTaskProxyless` y `HCaptchaTaskProxylessM1` tienen los mismos parámetros pero usan rutas distintas; puedes usar uno como respaldo del otro.
-   `HCaptchaTask` carga el captcha con tu propio proxy y requiere los campos de proxy; úsalo cuando el sitio de destino compruebe la IP de acceso.

## Parámetros de la solicitud

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `type` | string | Sí | Tipo de tarea; consulta "Tipos de tarea y precios" en esta página |
| `websiteURL` | string | Sí | URL completa de la página que muestra el captcha. Usa el sitio donde ves el captcha, no el dominio del proveedor del captcha |
| `websiteKey` | string | Sí | La clave del sitio (sitekey) de hCaptcha, normalmente un UUID |
| `userAgent` | string | No | User-Agent del navegador. Recomendado, pero solo se acepta el valor devuelto por `GET https://api.yescaptcha.com/useragent`; envía el token con el `userAgent` del resultado |
| `isInvisible` | boolean | No | Envía true para la variante invisible; en otro caso, omítelo |
| `rqdata` | string | No | rqdata de hCaptcha Enterprise; algunos sitios lo requieren y normalmente se encuentra en la solicitud que carga el captcha |
| `proxyType` | string | Algunos tipos | Protocolo del proxy: `http`, `https`, `socks4` o `socks5` (Obligatorio para HCaptchaTask) |
| `proxyAddress` | string | Algunos tipos | Dirección IP o nombre de host del proxy. Las direcciones locales o privadas como 127.0.0.1 o 192.168.x.x no funcionan porque nuestros servidores no pueden acceder a ellas (Obligatorio para HCaptchaTask) |
| `proxyPort` | integer | Algunos tipos | Puerto del proxy (Obligatorio para HCaptchaTask) |
| `proxyLogin` | string | No | Usuario del proxy, si el proxy requiere autenticación (solo HCaptchaTask) |
| `proxyPassword` | string | No | Contraseña del proxy, si el proxy requiere autenticación (solo HCaptchaTask) |

-   `websiteURL` es la página donde aparece el captcha, **no** hcaptcha.com.
-   `userAgent` es recomendable, y solo se acepta el valor devuelto por [/useragent](https://docs.yescaptcha.com/es/api/useragent.md).
-   `rqdata`: lo exigen los sitios con hCaptcha Enterprise (por ejemplo, algunos sitios sociales y de chat) y normalmente se encuentra en la solicitud que carga el captcha. En sitios normales, no lo envíes.

Para saber cómo encontrar los parámetros, consulta [Cómo encontrar los parámetros de hCaptcha](https://docs.yescaptcha.com/es/guides/find-hcaptcha-parameters.md).

## Ejemplo de solicitud

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

Con tu propio proxy:

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 | Descripción |
| --- | --- | --- |
| `gRecaptchaResponse` | string | El token que debes enviar al sitio de destino. De un solo uso, válido durante unos 120 segundos; úsalo en un plazo de 60 segundos |
| `userAgent` | string | El User-Agent usado para obtener el token. Usa este valor al enviar el token, aunque sea distinto del que enviaste |
| `respKey` | string | Un valor que algunos sitios exigen junto con el token; envíalo si está presente |

Al enviar:

1.  Coloca el token en el campo `h-captcha-response` de la página (y en `g-recaptcha-response`, si existe), o en el campo que exija la API del sitio de destino.
2.  Al enviar la solicitud, usa como User-Agent el `userAgent` devuelto.
3.  Si se devolvió un `respKey`, envíalo también según lo que pida el sitio.

Mientras la tarea está en proceso se devuelve `{"errorId": 0, "status": "processing"}`; consulta de nuevo 5 segundos después. Si hay un error, trátalo según el `errorCode`; consulta [Códigos de error](https://docs.yescaptcha.com/es/api/errors.md).

## Preguntas frecuentes

### ¿Por qué la tasa de éxito no es estable?

hCaptcha decide según la configuración del sitio, la IP de acceso y el entorno del navegador, por lo que la tasa de éxito varía de un sitio a otro. Comprueba que uses el `userAgent` devuelto; en sitios sensibles a la IP, usa `HCaptchaTask` con tu propio proxy y envía también el formulario a través del mismo proxy; también puedes comparar con `HCaptchaTaskProxylessM1`.

### ¿Cuánto tiempo es válido el token?

Es de un solo uso y es válido durante unos 120 segundos. Te recomendamos enviarlo lo antes posible.

## Tutoriales relacionados

-   [Cómo encontrar los parámetros de hCaptcha](https://docs.yescaptcha.com/es/guides/find-hcaptcha-parameters.md)
-   [Clics de reconocimiento de imágenes de hCaptcha con Selenium](https://docs.yescaptcha.com/es/guides/hcaptcha-click-selenium.md)