Skip to content
API
hCAPTCHA
Изображение

hCAPTCHA Image

Обзор

hCaptcha Image — это тип капчи, который требует от пользователей идентифицировать и выбирать изображения в соответствии с требованиями, кликать по точкам или перетаскивать изображения.

🖼️

hCaptcha Token широко используется на многих веб-сайтах, таких как Cloudflare, Discord, OpenSea и многих других сервисах для защиты от ботов.

hCaptcha Token BBox

1. Создание задачи

Запрос

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

Параметры

Имя параметраТип данныхОбязательно?Описание
clientKeystringдаApi ключ
task.typestringдаHCaptchaImageTask
task.subTypestringдаЗначение равно 0
task.imagestringдаСписок изображений в формате base64, разделенных |
base64_question1|base64_question2|...|base64_question9|base64_sample1|base64_sample2|...|base64_sampleN
Примечание: Образцы изображений могут присутствовать или отсутствовать. Изображения должны быть закодированы в base64
task.otherstringдаВопрос|Количество изображений|Тип капчи
Пример: "Please identify and click on all pictures featuring a bird|9|grid"
- Вопрос: "Please identify and click on all pictures featuring a bird"
- Количество изображений: 9 (Считать только изображения в сетке question, не sample)
- Тип капчи: grid (выбрать ячейки из 9, соответствующие условию) или bbox (кликнуть одну/несколько точек или перетащить для выделения объекта, соответствующего условию) или drag (перетащить один/несколько фрагментов пазла для создания полного изображения)

Пример запроса

POST /createTask HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
 
{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "HCaptchaImageTask",
    "subType": "0",
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==|iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==|...(9 base64 images joined by |)",
    "other": "Please identify and click on all pictures featuring a bird|9|grid"
  }
}

Ответ

При успехе сервер возвращает errorId = 0 и taskId

{
  "errorId": 0,
  "taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}

Примеры изображений для отправки на сервер решения капчи

Совет: Для наилучшего качества распознавания капчи, обрезайте изображение, как показано на красных и фиолетовых прямоугольниках на примерах ниже.
Убедитесь, что разрешение обрезанного изображения не менее 500–600 пикселей по ширине/высоте, чтобы получить оптимальные результаты.

Пример запроса Multi click

2. Получение результата

Запрос

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

Параметры

Имя параметраТип данныхОбязательно?Описание
clientKeystringдаApi ключ
taskIdstringдаTaskId, полученный из (1)

Пример запроса

POST /getTaskResult HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
 
{
  "clientKey": "YOUR_API_KEY",
  "taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}

Ответ

{
  "errorId": 0,
  "status": "ready",
  // solution: координаты точек для клика (x1,y1,x2,y2,...) 
  "solution": "20,30,40,50"
}

Пояснение статусов

  • errorId = 0 и status = ready: Успешно решено, читайте результат в solution.gRecaptchaResponse
  • errorId = 0 и status = processing: Решение капчи, подождите 2 секунды и попробуйте снова
  • errorId > 0: Системная ошибка, возвращает код ошибки и описание

Примеры интеграции

import requests
import time
import base64
 
def image_url_to_base64(url):
    """Convert image URL to 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='YOUR_API_KEY'):
    # Step 1: Create task
    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']
    
    # Step 2: Get result
    get_result_url = 'https://api.achicaptcha.com/getTaskResult'
    
    while True:
        time.sleep(2)  # Wait 2 seconds
        
        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']
        
        # If status == 'processing', continue loop
 
# Usage
# Convert image URLs to base64
image_urls = [
    'https://example.com/image1.jpg',
    'https://example.com/image2.jpg',
    # ... other images
    'https://example.com/image9.jpg'
]
 
base64_images = [image_url_to_base64(url) for url in image_urls]
image_base64_list = '|'.join(base64_images)
 
question = 'Please identify and click on all pictures featuring a bird'
image_count = 9
captcha_type = 'grid'  # or 'bbox'
 
token = solve_hcaptcha_image(image_base64_list, question, image_count, captcha_type, 'YOUR_API_KEY')
print('hCaptcha token:', token)

Коды общих ошибок

Код ошибкиОписаниеПримечания
0successУспешно
1processingВ обработке
2missing required fieldsОтсутствуют обязательные поля, проверьте параметры
3task not supportedТип задачи не поддерживается
4task creation failedОшибка создания задачи
5client key does not existAPI ключ не существует, проверьте API ключ
6insufficient account balanceНедостаточно средств на счете, пополните баланс
7task failed, please create a new taskЗадача не выполнена, пожалуйста, создайте новую задачу
8task ID does not existID задачи не существует

Лучшие практики

Для достижения наилучших результатов при использовании Achicaptcha API следуйте этим принципам:

1. Проверка входных данных

  • Проверяйте список изображений перед отправкой запроса
  • Изображения должны быть закодированы в base64 перед отправкой
  • Убедитесь в правильном формате: base64_image1|base64_image2|...|base64_image9 или с дополнительными образцами изображений
  • Проверьте точность вопроса и типа капчи (grid/bbox)
  • Количество изображений должно соответствовать фактическому количеству изображений в сетке

2. Обработка нескольких раундов

  • hCaptcha может требовать решения нескольких последовательных раундов
  • Achicaptcha API автоматически обрабатывает эти раунды
  • Время решения может быть больше, чем у текстовой капчи (15-30 секунд)

3. Интервал опроса

  • Ждите не менее 2 секунд между проверками результата
  • Не отправляйте слишком много последовательных запросов к API
  • Установите тайм-аут, чтобы избежать бесконечных циклов (рекомендуется 120 секунд)

4. Логика повторных попыток

  • Реализуйте повторные попытки для временных ошибок, таких как ERROR_NO_SLOT_AVAILABLE
  • Используйте экспоненциальную задержку при повторных попытках
  • Ограничьте максимальное количество попыток

5. Безопасность API ключа

  • Не прописывайте API ключ жестко в коде
  • Используйте переменные окружения
  • Не раскрывайте API ключ на стороне клиента

Полезные ссылки: