Skip to content
API
hCAPTCHA
Imagen

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.

hCaptcha Token BBox

1. Crear Tarea

Solicitud

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

Parámetros

Nombre del ParámetroTipo de Dato¿Requerido?Descripción
clientKeystringClave API
task.typestringHCaptchaImageTask
task.subTypestringEl valor es igual a 0
task.imagestringLista de imágenes en base64 separadas por |
base64_pregunta1|base64_pregunta2|...|base64_pregunta9|base64_muestra1|base64_muestra2|...|base64_muestraN
Nota: Las imágenes de muestra pueden estar presentes o no. Las imágenes deben estar codificadas en base64
task.otherstringPregunta|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.

Solicitud Multi clic

2. Obtener Resultado

Solicitud

POST https://api.achicaptcha.com/getTaskResult

Parámetros

Nombre del ParámetroTipo de Dato¿Requerido?Descripción
clientKeystringClave API
taskIdstringTaskId 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 = 0 y status = ready: Resuelto exitosamente, lee el resultado en solution.gRecaptchaResponse
  • errorId = 0 y status = processing: Resolviendo captcha, espera 2 segundos e intenta de nuevo
  • errorId > 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 ErrorDescripciónNotas
0éxitoÉxito
1procesandoProcesando
2faltan campos requeridosFaltan campos requeridos, verifica los parámetros nuevamente
3tarea no compatibleTipo de tarea no compatible
4creación de tarea fallidaCreación de tarea fallida
5la clave del cliente no existeLa clave API no existe, verifica la clave API nuevamente
6saldo de cuenta insuficienteSaldo de cuenta insuficiente, agrega más créditos
7tarea fallida, por favor crea una nueva tareaTarea fallida, por favor crea una nueva tarea
8el ID de tarea no existeEl 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_imagen9 o 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: