Tipos de tarea

hCaptcha

Esta página se tradujo automáticamente de la versión en chino y puede contener errores. Prevalece la versión en chino.

Soy humanohCaptchaPrivacidad - Condiciones

IlustraciónhCaptcha: una casilla "Soy humano". Al hacer clic, se marca de inmediato o se abre un desafío de imágenes.

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.

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

POSThttps://cn.yescaptcha.com/createTaskEndpoint 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.

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.
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.

Ejemplo de solicitud

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

Con tu propio 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"
  }
}

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	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:

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.
Al enviar la solicitud, usa como User-Agent el userAgent devuelto.
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.

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.