Skip to main content
В данной статье будет представлена инструкция по интеграции hCaptcha протокола распознавания API, которая позволяет пользователям не распознавать и не нажимать на изображения hCaptcha, а просто отправить Website Key для автоматической декодировки на сервере и завершения верификации.

​
Процесс подачи заявки

Чтобы использовать hCaptcha протокол распознавания API, сначала перейдите в консоль Ace Data Cloud и получите ваш API Token для резервного копирования. Если вы еще не вошли в систему или не зарегистрированы, вас автоматически перенаправит на страницу входа, где вас пригласят зарегистрироваться и войти. После завершения вы автоматически вернетесь на текущую страницу. Один API Token позволяет использовать все услуги платформы, не нужно подавать отдельные заявки на каждую услугу. При первой подаче заявки предоставляется бесплатный лимит для тестирования; при недостатке лимита вы можете пополнить общий баланс в консоли.
📘 Полная документация: hCaptcha Протокол Распознавания API →

​
Основное использование

Сначала ознакомьтесь с основным способом использования, который заключается в вводе URL сайта, на котором нужно обработать hCaptcha, чтобы получить обработанный результат. Сначала необходимо просто передать поле website_url, наш пример сайта: https://accounts.hcaptcha.com/demo, нам нужно получить website_key на странице website_url, для этого откройте эту веб-страницу, нажмите F12 для входа в консоль, и затем выполните глобальный поиск по элементам на странице hcaptcha-demo, мы можем получить следующий результат:

Где строка, соответствующая data-sitekey, является значением website_key, ниже приведены конкретные параметры результата:

Здесь мы видим, что мы установили заголовки запроса, включая:
  • accept: формат ответа, который вы хотите получить, здесь указано application/json, то есть формат JSON.
  • authorization: ключ для вызова API, после подачи заявки его можно выбрать из выпадающего списка.
Также установлен Body запроса, включая:
  • website_url: URL сайта, на котором нужно обработать капчу.
  • website_key: идентификатор сайта в hCaptcha.
  • rqdata: необязательный. Вызов hCaptcha Enterprise может предоставить data-rqdata на странице, в случае таких вызовов укажите его исходное значение; обычная hCaptcha не требует заполнения.
  • proxy: необязательный, собственный прокси (Bring Your Own Proxy). После установки система будет использовать предоставленный вами IP прокси для решения капчи, чтобы контролировать качество выходного IP (например, избежать блокировки целевым сайтом из-за использования общих прокси IP, что может привести к возврату 410 Gone). Формат: scheme://[user:pass@]host:port, scheme поддерживает http/https/socks4/socks5, например, http://user:pass@1.2.3.4:8080. Если не указано, будет использоваться прокси по умолчанию от платформы.
После выбора вы также можете заметить, что справа сгенерирован соответствующий код, как показано на изображении:

Нажмите кнопку «Попробовать», чтобы провести тестирование, как показано на изображении выше, и мы получили следующий результат:
Результат запроса содержит несколько полей, описание которых приведено ниже:
  • token — результат проверки после обработки задачи hCaptcha.
  • started_at, finished_at — время начала обработки запроса и получения результата, Unix временная метка (секунды, с плавающей запятой).
  • elapsed — общее время обработки (в секундах). 可以看到我们得到了处理 hCaptcha验证码 的验证结果，然后我们可以用于POST或模拟提交给目标网站，一次性使用，有效期120s，建议在60s内使用，接下来将提供一段CURL版本将处理后token提交到目标网站来通过Recaptcha2验证码。
首先我们需要获取网站是如何发送POST请求，这样我们才能将生成的token传入进去，我们需要先打开F12控制台，然后人工先通过一下，最后我们可以看到网站发送了一个POST请求，我们只需要查看这次的POST请求构造，具体的过程如下：
  • 先人工通过验证，具体的如下图：

  • 再点击submit，观看控制台的network变化，具体的如下图：

  • 分析此次提交的POST请求构造，最后可以右键该请求复制CURL的代码，具体的如下图：

由上图分析可知，此次POST请求的URL为：https://accounts.hcaptcha.com/demo，我们仅需要提交参数 g-recaptcha-response、h-captcha-response 和 email，然后我们只需要将处理后的token传入下面的data中即可，调用token验证所对应CURL代码如下：
调用token验证所对应的Python代码如下：
然后我们观察控制台变得了这样的结果：

最后我们就通过了hCaptcha验证码的验证。 另外如果想生成对应的对接代码，可以直接复制生成，例如 CURL 的代码如下：
Python 的对接代码如下：

​
异步模式（async）

默认情况下 API 是同步阻塞的：一次请求会一直等待，直到 token 处理完成才返回。如果你在做多打码器轮换（multi-solver rotation），希望「提交任务后立即拿到 task_id，先去调度其他打码器，稍后再回来读取结果」，可以在请求体中传入 async: true。 传入 async: true 后，接口会立即返回一个 task_id，而不会阻塞等待：
如需主动查看进度，可使用该 task_id 查询 POST /captcha/tasks（建议每 3~5 秒一次）。本接口不会触发或推进任务处理；即使不查询、断网或退出客户端，服务器仍会继续处理：
处理中会返回 status: processing：
处理完成会返回 status: ready 和 token：
计费说明：异步模式下，创建任务和读取「处理中」状态都不计费；客户端首次读取成功结果时计费一次（与现有行为及同步模式价格一致）。服务器会自主推进任务，但不会因为后台先完成就提前扣费。任务在 120 秒内未成功会终止为 HTTP 504 timeout，不计费。/captcha/tasks 不负责推进任务。

​
错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：
  • 400 token_mismatched：Bad request, possibly due to missing or invalid parameters.
  • 400 api_not_implemented：Bad request, possibly due to missing or invalid parameters.
  • 401 invalid_token：Unauthorized, invalid or missing authorization token.
  • 429 too_many_requests：Too many requests, you have exceeded the rate limit.
  • 500 api_error：Internal server error, something went wrong on the server.

​
错误响应示例

​
结论

通过本文档，您已经了解了如何使用 hCaptcha 协议识别 API 让用户无需识别和点选 hCaptcha 验证码图片，仅需通过提交 Website Key 即可实现后台自动解码，完成验证。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。