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.

1. Tạo yêu cầu
Request
POST https://api.achicaptcha.com/createTask
Tham số
| Tên param | Kiểu dữ liệu | Bắt buộc? | Mô tả |
|---|---|---|---|
clientKey | string | yes | Api key |
task.type | string | yes | HCaptchaImageTask |
task.subType | string | yes | Giá trị bằng 0 |
task.image | string | yes | Danh 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_sampleNLưu ý: ảnh image sample có thể có hoặc không. Hình ảnh phải được encode sang base64 |
task.other | string | yes | Câ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 = 0 và taskId
{
"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.

2. Lấy kết quả
Request
POST https://api.achicaptcha.com/getTaskResult
Tham số
| Tên param | Kiểu dữ liệu | Bắt buộc? | Mô tả |
|---|---|---|---|
clientKey | string | yes | Api key |
taskId | string | yes | TaskId 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 = 0vàstatus = ready: Giải thành công, đọc kết quả trongsolution.gRecaptchaResponseerrorId = 0vàstatus = processing: Đang giải captcha, đợi 2 giây rồi thử lạierrorId > 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ỗi | Mô tả | Chú thích |
|---|---|---|
| 0 | success | Thành công |
| 1 | processing | Đang xử lý |
| 2 | missing required fields | Thiếu trường bắt buộc, kiểm tra lại tham số |
| 3 | task not supported | Loại task không được hỗ trợ |
| 4 | task creation failed | Tạo task thất bại |
| 5 | client key does not exist | API key không tồn tại, kiểm tra lại API key |
| 6 | insufficient account balance | Số dư tài khoản không đủ, nạp thêm credit |
| 7 | task failed, please create a new task | Task thất bại, vui lòng tạo task mới |
| 8 | task ID does not exist | Task 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_image9hoặ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: