hCAPTCHA Imagen
Descripción General
hCaptcha Imagen es un tipo de captcha que requiere que los usuarios identifiquen y seleccionen imágenes según los requisitos, hagan clic en puntos o arrastren imágenes.
hCaptcha Token se usa ampliamente en muchos sitios web como Cloudflare, Discord, OpenSea y muchos otros servicios para proteger contra bots.

1. Crear Tarea
Solicitud
POST https://api.achicaptcha.com/createTask
Parámetros
| Nombre del Parámetro | Tipo de Dato | ¿Requerido? | Descripción |
|---|---|---|---|
clientKey | string | sí | Clave API |
task.type | string | sí | HCaptchaImageTask |
task.subType | string | sí | El valor es igual a 0 |
task.image | string | sí | Lista de imágenes en base64 separadas por |base64_pregunta1|base64_pregunta2|...|base64_pregunta9|base64_muestra1|base64_muestra2|...|base64_muestraNNota: Las imágenes de muestra pueden estar presentes o no. Las imágenes deben estar codificadas en base64 |
task.other | string | sí | Pregunta|Cantidad de imágenes|Tipo de captcha Ejemplo: "Por favor identifique y haga clic en todas las imágenes que muestran un pájaro|9|grid"- Pregunta: "Por favor identifique y haga clic en todas las imágenes que muestran un pájaro" - Cantidad de imágenes: 9 (Solo cuenta las imágenes en la cuadrícula de pregunta, no las imágenes de muestra)- Tipo de captcha: grid (seleccionar celdas en 9 celdas que cumplan la condición) o bbox (hacer clic en uno/múltiples puntos o arrastrar para marcar un objeto que cumpla la condición) o drag (arrastrar una/múltiples piezas de rompecabezas para crear una imagen completa) |
Ejemplo de Solicitud
POST /createTask HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
{
"clientKey": "TU_CLAVE_API",
"task": {
"type": "HCaptchaImageTask",
"subType": "0",
"image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==|iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==|...(9 imágenes base64 unidas por |)",
"other": "Por favor identifique y haga clic en todas las imágenes que muestran un pájaro|9|grid"
}
}Respuesta
Cuando tiene éxito, el servidor devuelve errorId = 0 y taskId
{
"errorId": 0,
"taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}Imágenes de ejemplo para enviar al servidor de resolución de captcha
Consejo: Para obtener la mejor calidad en el reconocimiento del captcha, recorta tu imagen como se muestra en los cuadros rojos y morados en los ejemplos de abajo.
Asegúrate de que la resolución de la imagen recortada tenga al menos 500–600 píxeles de ancho/alto para mejores resultados.

2. Obtener Resultado
Solicitud
POST https://api.achicaptcha.com/getTaskResult
Parámetros
| Nombre del Parámetro | Tipo de Dato | ¿Requerido? | Descripción |
|---|---|---|---|
clientKey | string | sí | Clave API |
taskId | string | sí | TaskId obtenido de (1) |
Ejemplo de Solicitud
POST /getTaskResult HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
{
"clientKey": "TU_CLAVE_API",
"taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}Respuesta
{
"errorId": 0,
"status": "ready",
// solution: coordenadas de puntos para hacer clic (x1,y1,x2,y2,...)
"solution": "20,30,40,50"
}Explicación del Estado
errorId = 0ystatus = ready: Resuelto exitosamente, lee el resultado ensolution.gRecaptchaResponseerrorId = 0ystatus = processing: Resolviendo captcha, espera 2 segundos e intenta de nuevoerrorId > 0: Error del sistema, devuelve código de error y descripción
Ejemplos de Integración
import requests
import time
import base64
def image_url_to_base64(url):
"""Convertir URL de imagen a base64"""
response = requests.get(url)
return base64.b64encode(response.content).decode('utf-8')
def solve_hcaptcha_image(image_base64_list, question, image_count, captcha_type, api_key='TU_CLAVE_API'):
# Paso 1: Crear tarea
create_task_url = 'https://api.achicaptcha.com/createTask'
create_task_payload = {
'clientKey': api_key,
'task': {
'type': 'HCaptchaImageTask',
'subType': '0',
'image': image_base64_list,
'other': f'{question}|{image_count}|{captcha_type}'
}
}
response = requests.post(create_task_url, json=create_task_payload)
result = response.json()
if result['errorId'] != 0:
raise Exception(result['errorDescription'])
task_id = result['taskId']
# Paso 2: Obtener resultado
get_result_url = 'https://api.achicaptcha.com/getTaskResult'
while True:
time.sleep(2) # Esperar 2 segundos
get_result_payload = {
'clientKey': api_key,
'taskId': task_id
}
response = requests.post(get_result_url, json=get_result_payload)
result = response.json()
if result['errorId'] != 0:
raise Exception(result['errorDescription'])
if result['status'] == 'ready':
return result['solution']['gRecaptchaResponse']
# Si status == 'processing', continuar el bucle
# Uso
# Convertir URLs de imágenes a base64
image_urls = [
'https://example.com/image1.jpg',
'https://example.com/image2.jpg',
# ... otras imágenes
'https://example.com/image9.jpg'
]
base64_images = [image_url_to_base64(url) for url in image_urls]
image_base64_list = '|'.join(base64_images)
question = 'Por favor identifique y haga clic en todas las imágenes que muestran un pájaro'
image_count = 9
captcha_type = 'grid' # o 'bbox'
token = solve_hcaptcha_image(image_base64_list, question, image_count, captcha_type, 'TU_CLAVE_API')
print('Token hCaptcha:', token)Códigos de Error Comunes
| Código de Error | Descripción | Notas |
|---|---|---|
| 0 | éxito | Éxito |
| 1 | procesando | Procesando |
| 2 | faltan campos requeridos | Faltan campos requeridos, verifica los parámetros nuevamente |
| 3 | tarea no compatible | Tipo de tarea no compatible |
| 4 | creación de tarea fallida | Creación de tarea fallida |
| 5 | la clave del cliente no existe | La clave API no existe, verifica la clave API nuevamente |
| 6 | saldo de cuenta insuficiente | Saldo de cuenta insuficiente, agrega más créditos |
| 7 | tarea fallida, por favor crea una nueva tarea | Tarea fallida, por favor crea una nueva tarea |
| 8 | el ID de tarea no existe | El ID de tarea no existe |
Mejores Prácticas
Para obtener los mejores resultados al usar la API de Achicaptcha, sigue estos principios:
1. Validar Datos de Entrada
- Verifica la lista de imágenes antes de enviar la solicitud
- Las imágenes deben estar codificadas en base64 antes de enviarlas
- Asegúrate del formato correcto:
base64_imagen1|base64_imagen2|...|base64_imagen9o con imágenes de muestra adicionales - Verifica que la pregunta y el tipo de captcha (grid/bbox) sean precisos
- El recuento de imágenes debe coincidir con el número real de imágenes en la cuadrícula
2. Manejar Múltiples Rondas
- hCaptcha puede requerir resolver múltiples rondas consecutivas
- La API de Achicaptcha maneja automáticamente estas rondas
- El tiempo de resolución puede ser más largo que el captcha de texto (15-30 segundos)
3. Intervalo de Sondeo
- Espera al menos 2 segundos entre verificaciones de resultado
- No envíes spam a la API con demasiadas solicitudes consecutivas
- Establece un tiempo de espera para evitar bucles infinitos (recomendado 120 segundos)
4. Lógica de Reintento
- Implementa reintento para errores temporales como
ERROR_NO_SLOT_AVAILABLE - Usa retroceso exponencial al reintentar
- Limita los intentos máximos de reintento
5. Seguridad de la Clave API
- No codifiques la clave API en el código
- Usa variables de entorno
- No expongas la clave API en el lado del cliente
Enlaces útiles: