hCAPTCHA 图片
概述
hCaptcha 图片是一种验证码类型,要求用户根据要求识别和选择图片、点击点或拖动图片。
🖼️
hCaptcha Token 被许多网站广泛使用,如 Cloudflare、Discord、OpenSea 和许多其他服务,以防止机器人。

1. 创建任务
请求
POST https://api.achicaptcha.com/createTask
参数
| 参数名称 | 数据类型 | 是否必需 | 描述 |
|---|---|---|---|
clientKey | string | 是 | API密钥 |
task.type | string | 是 | HCaptchaImageTask |
task.subType | string | 是 | 值等于 0 |
task.image | string | 是 | 用 | 分隔的base64图片列表base64_question1|base64_question2|...|base64_question9|base64_sample1|base64_sample2|...|base64_sampleN注意: 样本图片可能存在也可能不存在。图片必须编码为base64 |
task.other | string | 是 | 问题|图片数量|验证码类型 示例: "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像素的宽/高,以保证最佳效果。

2. 获取结果
请求
POST https://api.achicaptcha.com/getTaskResult
参数
| 参数名称 | 数据类型 | 是否必需 | 描述 |
|---|---|---|---|
clientKey | string | 是 | API密钥 |
taskId | string | 是 | 从(1)获取的TaskId |
请求示例
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):
"""将图片URL转换为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'):
# 步骤1:创建任务
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']
# 步骤2:获取结果
get_result_url = 'https://api.achicaptcha.com/getTaskResult'
while True:
time.sleep(2) # 等待2秒
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']
# 如果 status == 'processing',继续循环
# 使用方法
# 将图片URL转换为base64
image_urls = [
'https://example.com/image1.jpg',
'https://example.com/image2.jpg',
# ... 其他图片
'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' # 或 'bbox'
token = solve_hcaptcha_image(image_base64_list, question, image_count, captcha_type, 'YOUR_API_KEY')
print('hCaptcha token:', token)常见错误代码
| 错误代码 | 描述 | 备注 |
|---|---|---|
| 0 | 成功 | 成功 |
| 1 | 处理中 | 处理中 |
| 2 | 缺少必填字段 | 缺少必填字段,请再次检查参数 |
| 3 | 不支持的任务 | 不支持的任务类型 |
| 4 | 任务创建失败 | 任务创建失败 |
| 5 | 客户端密钥不存在 | API密钥不存在,请再次检查API密钥 |
| 6 | 账户余额不足 | 账户余额不足,请充值 |
| 7 | 任务失败,请创建新任务 | 任务失败,请创建新任务 |
| 8 | 任务ID不存在 | 任务ID不存在 |
最佳实践
为了在使用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密钥
有用的链接: