在本文中，我们将介绍如何集成 hCaptcha 图像识别 API，该 API 能够识别用户输入的内容和 hCaptcha 验证图像，最终返回需要点击的小图像的坐标。通过这一集成，开发者可以在应用中实现自动化的验证码处理，提高用户体验。
背景介绍
hCaptcha 是一种常用的验证码技术，旨在防止机器人自动提交表单。Ace Data Cloud 提供的 hCaptcha 图像识别 API 使得开发者能够自动识别并处理这些验证码，从而提升用户体验。特别是在需要用户频繁通过验证的场景中，使用此 API 可以大大提升效率。
申请使用 API
要使用 hCaptcha 图像识别 API，您需要首先在 hCaptcha 图像识别 API 页面 申请相应的服务。进入页面后，点击“Acquire”按钮，如下图所示：
如果您尚未登录或注册，将自动重定向至登录页面。登录或注册后，您将被带回当前页面。首次申请的用户可以获得免费的配额，允许您免费使用 API。
基本用法
使用该 API 的基本方法是输入需要处理的 hCaptcha 验证图像以获得处理结果。您需要在请求中传递一个 queries 字段，内容为特定的 hCaptcha 验证图像。您可以从一个具有 hCaptcha 验证的网站捕获此图像，例如 Demo Captcha。点击复选框以显示完整的验证图像，如下图所示：
queries 字段应为上述验证图像的截图。建议图像大小不超过 100kb。您还需要截取图中红色箭头指示的区域，压缩图像大小，并转换为 Base64 编码，如下图所示：
除了 queries，还需要输入与验证图像相关的识别内容参数 question。该参数支持中文和英文输入，示例内容为：Please click on the UNIQUE object among the others. 具体内容如下：
在设置请求头时，您需要包括：
accept: 希望接收的响应结果格式，这里填写为application/json。authorization: 调用 API 的密钥，可以在申请后直接选择。
同时设置请求体，包括：
queries: Base64 编码的验证图像列表。question: 与验证图像相关的识别内容参数，支持直接输入中文和英文。
选择后，您可以在右侧看到相应的代码生成，如下图所示：
点击“Try”按钮进行测试，如上图所示。我们获得了以下结果：
{
"solution": {
"label": "Please click on the UNIQUE object among the others",
"box": [
"360",
"276"
],
"confidences": 0.6354503631591797
}
}
返回的结果包含多个字段，具体描述如下：
solution: 处理后 hCaptcha 验证图像任务的结果。label: 从 hCaptcha 验证图像中识别出的内容。box: 识别结果的位置信息，由图像的坐标信息组成。confidences: 识别内容的置信度。
通过这些信息，我们可以模拟在 box 位置的坐标上点击，以通过验证。
点击模拟
根据结果中的 box 位置信息，我们需要建立一个直角坐标系，以上传的验证图像的左下角为原点。水平坐标为 360，垂直坐标为 276。只需在对应的坐标位置模拟点击，如下图所示：
如果您想生成相应的集成代码，可以直接复制，例如，CURL 代码如下：
curl -X POST 'https://api.acedata.cloud/captcha/recognition/hcaptcha' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"question": "Please click on the UNIQUE object among the others.",
"queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"]
}'
Python 集成代码如下：
import requests
url = "https://api.acedata.cloud/captcha/recognition/hcaptcha"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"question": "Please click on the UNIQUE object among the others.",
"queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"]
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
错误处理
在调用 API 时，如果发生错误，API 将返回相应的错误代码和信息。例如：
400 token_mismatched: 错误请求，可能由于缺少或无效参数。401 invalid_token: 未授权，密钥无效或缺失。429 too_many_requests: 请求过多，超出速率限制。500 api_error: 服务器内部错误。
错误响应示例
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
总结
通过本文，您了解了如何使用 hCaptcha 图像识别 API，让用户输入识别的内容和 hCaptcha 验证图像，并返回需要点击的小图像坐标。希望这份指南能够帮助您更好地集成和使用该 API。如有任何疑问，请随时联系技术支持团队。
技术标签：#hCaptcha #API #图像识别 #AceDataCloud #自动化
