hCaptcha 图像识别 API 对接说明

一、hCaptcha 图像识别 API 简介

hCaptcha 是一种基于机器学习与人工智能的图像识别验证服务，旨在通过交互式图像分类任务区分人类用户与自动化脚本。相较于传统验证码，hCaptcha 的图像识别 API 提供了更高的安全性与用户体验，支持动态调整难度、多语言适配及自定义主题。其核心优势在于：

1. 安全性：通过图像分类任务有效抵御自动化攻击。
2. 用户体验：减少用户输入负担，支持无障碍访问。
3. 灵活性：提供多种验证模式（如滑动拼图、多选分类）及主题定制。
4. 数据隐私：符合 GDPR 等隐私法规，用户数据仅用于验证目的。

二、对接前准备工作

1. 注册 hCaptcha 账户

访问 hCaptcha 官网 注册开发者账户，完成邮箱验证后获取 API 密钥（Site Key 和 Secret Key）。Site Key 用于前端验证，Secret Key 用于后端验证结果。

2. 选择验证模式

hCaptcha 提供多种验证模式，需根据业务场景选择：

• Checkbox 模式：用户勾选“我不是机器人”复选框触发验证。
• Invisible 模式：后台自动触发验证，用户无感知。
• Challenge 模式：强制用户完成图像分类任务（适用于高风险场景）。

3. 环境准备

• 前端：支持 HTML5 的浏览器（Chrome、Firefox、Safari 等）。
• 后端：需具备 HTTPS 协议支持，推荐使用 Node.js、Python、Java 等主流语言。
• 依赖库：根据语言选择官方 SDK（如 hcaptcha-node、hcaptcha-python）或直接调用 REST API。

三、对接步骤详解

1. 前端集成

（1）引入 hCaptcha 脚本

在 HTML 头部添加以下代码：

<script src="https://js.hcaptcha.com/1/api.js" async defer></script>

（2）添加验证容器

在表单中插入 hCaptcha 容器，并指定 sitekey 和模式：

<div class="h-captcha" data-sitekey="YOUR_SITE_KEY" data-theme="dark"></div>

• data-theme：可选 light 或 dark 主题。
• data-size：可选 normal、compact 或 invisible。

（3）监听验证事件

通过 JavaScript 监听验证结果：

document.querySelector('form').addEventListener('submit', async (e) => {
  e.preventDefault();
  const token = document.querySelector('.h-captcha-response').value;
  if (!token) {
    alert('请完成验证');
    return;
  }
  // 提交 token 到后端验证
  const response = await fetch('/verify', {
    method: 'POST',
    body: JSON.stringify({ token }),
    headers: { 'Content-Type': 'application/json' }
  });
  const data = await response.json();
  if (data.success) {
    alert('验证通过');
  } else {
    alert('验证失败');
  }
});

2. 后端验证

（1）调用验证 API

使用 Secret Key 验证前端返回的 h-captcha-response：

import requests
def verify_hcaptcha(token, secret_key):
    url = 'https://hcaptcha.com/siteverify'
    params = {
        'secret': secret_key,
        'response': token
    }
    response = requests.post(url, data=params)
    return response.json()

（2）处理验证结果

验证响应包含以下字段：

• success：布尔值，表示验证是否通过。
• challenge_ts：验证时间戳。
• hostname：验证请求的域名（用于防止跨域攻击）。
• error-codes：失败时的错误码（如 missing-input-response）。

示例响应：

{
  "success": true,
  "challenge_ts": "2023-10-01T12:00:00Z",
  "hostname": "example.com"
}

3. 错误处理

常见错误及解决方案：

• invalid-sitekey：检查 Site Key 是否正确。
• missing-input-response：确保前端已返回 h-captcha-response。
• timeout-or-duplicate：验证请求超时或重复，需重新触发验证。

四、高级功能与优化

1. 自定义难度

通过 data-difficulty 参数调整验证难度（如 easy、medium、hard）。

2. 多语言支持

hCaptcha 默认支持 20+ 种语言，可通过 data-hl 指定语言代码（如 zh-CN）。

3. 性能优化

• 缓存验证结果：对高频请求可缓存验证结果（需结合 Session 管理）。
• 异步加载：通过 async defer 延迟加载脚本，减少首屏渲染时间。
• CDN 加速：使用 hCaptcha 提供的 CDN 链接确保脚本快速加载。

4. 安全建议

• HTTPS 强制：确保所有验证请求通过 HTTPS 传输。
• IP 限制：对后端验证接口添加 IP 白名单。
• 日志监控：记录验证失败日志，分析异常请求模式。

五、常见问题解答

1. 验证失败但用户已完成任务？

可能原因：

• 后端 Secret Key 错误。
• 请求域名与 hCaptcha 注册域名不一致。
• 用户多次提交导致 Token 失效。

2. 如何测试对接效果？

hCaptcha 提供测试模式，通过设置 data-size="invisible" 和 data-debug="true" 可在控制台查看详细日志。

3. 收费模式如何？

hCaptcha 采用按验证次数计费，免费层提供每月 1,000 次验证，超出后按 $1.50/千次收费。

六、总结

hCaptcha 图像识别 API 的对接需关注前后端协同、错误处理及性能优化。通过合理选择验证模式、定制主题及语言，可显著提升用户体验与系统安全性。建议开发者在对接后持续监控验证日志，及时调整策略以应对新型攻击手段。