Skip to content
API
hCAPTCHA
图片

hCAPTCHA 图片

概述

hCaptcha 图片是一种验证码类型,要求用户根据要求识别和选择图片、点击点或拖动图片。

🖼️

hCaptcha Token 被许多网站广泛使用,如 Cloudflare、Discord、OpenSea 和许多其他服务,以防止机器人。

hCaptcha Token BBox

1. 创建任务

请求

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

参数

参数名称数据类型是否必需描述
clientKeystringAPI密钥
task.typestringHCaptchaImageTask
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 = 0taskId

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

上传到验证码识别服务器的图片样例

提示: 为获得最佳验证码识别质量,请按下方样例图片中的红色和紫色框进行裁剪。
请确保裁剪后的图片分辨率至少为500–600像素的宽/高,以保证最佳效果。

请求多点点击样例

2. 获取结果

请求

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

参数

参数名称数据类型是否必需描述
clientKeystringAPI密钥
taskIdstring从(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 = 0status = ready:成功解决,在 solution.gRecaptchaResponse 中读取结果
  • errorId = 0status = 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密钥

有用的链接: