Skip to content
API
hCAPTCHA
Giải hình ảnh

hCAPTCHA Image

Tổng quan

hCaptcha Image là loại captcha yêu cầu người dùng nhận dạng và chọn hình ảnh theo yêu cầu hoặc click điểm hoặc kéo hình ảnh.

🖼️

hCaptcha Token được sử dụng rộng rãi trên nhiều website như Cloudflare, Discord, OpenSea và nhiều dịch vụ khác để bảo vệ khỏi bot.

hCaptcha Token BBox

1. Tạo yêu cầu

Request

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

Tham số

Tên paramKiểu dữ liệuBắt buộc?Mô tả
clientKeystringyesApi key
task.typestringyesHCaptchaImageTask
task.subTypestringyesGiá trị bằng 0
task.imagestringyesDanh sách hình ảnh dạng base64, ngăn cách nhau bởi dấu |
base64_question1|base64_question2|...|base64_question9|base64_sample1|base64_sample2|...|base64_sampleN
Lưu ý: ảnh image sample có thể có hoặc không. Hình ảnh phải được encode sang base64
task.otherstringyesCâu hỏi|Số lượng hình|Loại captcha
Ví dụ: "Please identify and click on all pictures featuring a bird|9|grid"
- Câu hỏi: "Please identify and click on all pictures featuring a bird"
- Số lượng hình: 9 (Chỉ tính số lượng ảnh trong grid question, không tính ảnh mẫu sample)
- Loại captcha: grid (loại chọn các ô trong 9 ô thoả mãn điều kiện) hoặc bbox (loại chọn vào một/nhiều điểm hoặc kéo khoanh một vật thoả mãn điều kiện) hoặc drag (loại kéo thả một/nhiều mảnh ghép để tạo hình hoàn chỉnh)

Ví dụ Request

POST /createTask HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
 
{
  "clientKey": "API_KEY của bạn",
  "task": {
    "type": "HCaptchaImageTask",
    "subType": "0",
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==|iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==|...(9 ảnh base64 được nối bởi |)",
    "other": "Please identify and click on all pictures featuring a bird|9|grid"
  }
}

Response

Khi thành công, server sẽ trả về errorId = 0taskId

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

Các mẫu hình ảnh gửi lên server giải captcha

Mẹo: Để có chất lượng nhận diện captcha tốt nhất, hãy cắt (crop) hình ảnh của bạn như minh họa ở các khung đỏ và tím trên các hình mẫu bên dưới.
Đảm bảo hình ảnh sau khi cắt có độ phân giải ít nhất 500–600 pixel chiều rộng/cao để cho kết quả tốt nhất.

Mẫu Request Multi click

2. Lấy kết quả

Request

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

Tham số

Tên paramKiểu dữ liệuBắt buộc?Mô tả
clientKeystringyesApi key
taskIdstringyesTaskId lấy từ (1)

Ví dụ Request

POST /getTaskResult HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
 
{
  "clientKey": "API_KEY của bạn",
  "taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}

Response

{
  "errorId": 0,
  "status": "ready",
  // solution: các tọa độ điểm cần click (x1,y1,x2,y2,...) 
  "solution": "20,30,40,50"
}

Giải thích trạng thái

  • errorId = 0status = ready: Giải thành công, đọc kết quả trong solution.gRecaptchaResponse
  • errorId = 0status = processing: Đang giải captcha, đợi 2 giây rồi thử lại
  • errorId > 0: Lỗi hệ thống, đưa ra mã lỗi và mô tả lỗi

Ví dụ tích hợp

import requests
import time
import base64
 
def image_url_to_base64(url):
    """Chuyển đổi image URL sang 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'):
    # Bước 1: Tạo 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']
    
    # Bước 2: Lấy kết quả
    get_result_url = 'https://api.achicaptcha.com/getTaskResult'
    
    while True:
        time.sleep(2)  # Đợi 2 giây
        
        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']
        
        # Nếu status == 'processing', tiếp tục loop
 
# Sử dụng
# Chuyển đổi các URL hình ảnh sang base64
image_urls = [
    'https://example.com/image1.jpg',
    'https://example.com/image2.jpg',
    # ... các ảnh khác
    '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'  # hoặc 'bbox'
 
token = solve_hcaptcha_image(image_base64_list, question, image_count, captcha_type, 'YOUR_API_KEY')
print('hCaptcha token:', token)

Các mã lỗi thường gặp

Mã lỗiMô tảChú thích
0successThành công
1processingĐang xử lý
2missing required fieldsThiếu trường bắt buộc, kiểm tra lại tham số
3task not supportedLoại task không được hỗ trợ
4task creation failedTạo task thất bại
5client key does not existAPI key không tồn tại, kiểm tra lại API key
6insufficient account balanceSố dư tài khoản không đủ, nạp thêm credit
7task failed, please create a new taskTask thất bại, vui lòng tạo task mới
8task ID does not existTask ID không tồn tại

Best Practices

Để đạt hiệu quả tốt nhất khi sử dụng API Achicaptcha, hãy tuân thủ các nguyên tắc sau:

1. Validate dữ liệu đầu vào

  • Kiểm tra danh sách hình ảnh trước khi gửi request
  • Hình ảnh phải được encode sang base64 trước khi gửi
  • Đảm bảo format đúng: base64_image1|base64_image2|...|base64_image9 hoặc có thêm image sample
  • Xác minh câu hỏi (question) và loại captcha (grid/bbox) chính xác
  • Số lượng hình phải khớp với số ảnh thực tế trong grid

2. Handle multiple rounds

  • hCaptcha có thể yêu cầu giải nhiều vòng liên tiếp
  • API Achicaptcha tự động xử lý các vòng này
  • Thời gian giải có thể lâu hơn so với text captcha (15-30 giây)

3. Polling interval

  • Đợi ít nhất 2 giây giữa các lần kiểm tra kết quả
  • Không spam API với quá nhiều request liên tiếp
  • Có timeout để tránh vòng lặp vô hạn (khuyến nghị 120 giây)

4. Retry logic

  • Implement retry cho các lỗi tạm thời như ERROR_NO_SLOT_AVAILABLE
  • Sử dụng exponential backoff khi retry
  • Giới hạn số lần retry tối đa

5. Bảo mật API key

  • Không hardcode API key trong code
  • Sử dụng biến môi trường
  • Không expose API key ra client-side

Liên kết hữu ích: