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

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

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

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

Сначала ознакомьтесь с основным способом использования, который заключается в том, чтобы ввести изображение hCaptcha, которое нужно обработать, чтобы получить обработанный результат. Сначала необходимо просто передать поле queries, которое представляет собой конкретное изображение hCaptcha. Мы должны сделать скриншот этого изображения с сайта, где есть hCaptcha, пример ссылки на сайт: https://democaptcha.com/demo-form-eng/hcaptcha.html, кликнув по флажку, вы сможете увидеть полное изображение кода проверки, как показано на следующем изображении:

Поле queries — это скриншот изображения кода проверки, рекомендуется, чтобы размер изображения не превышал 100 КБ. Также необходимо сделать скриншот области, на которую указывает красная стрелка на изображении выше, и вам нужно самостоятельно сжать размер изображения, а также преобразовать его в кодировку Base64, как показано на следующем изображении:

Также необходимо ввести параметр распознавания, связанный с изображением кода проверки, question, который поддерживает перевод на китайский и английский языки. Вы можете напрямую передать соответствующее содержимое распознавания. Из содержимого, выполненного желтой стрелкой на изображении выше, видно, что question должно быть: Please click on the UNIQUE object among the others.. Конкретное содержимое следующее:

Как видно, мы установили заголовки запроса, включая:
  • accept: формат ответа, который вы хотите получить, здесь указано application/json, то есть формат JSON.
  • authorization: ключ для вызова API, который можно выбрать из выпадающего списка после подачи заявки.
Кроме того, установлены тело запроса, включая:
  • queries: список изображений кода проверки в кодировке Base64.
  • question: параметр распознавания, связанный с изображением кода проверки, поддерживает прямой ввод на китайском и английском языках.
После выбора вы также можете увидеть сгенерированный соответствующий код справа, как показано на изображении:

Нажмите кнопку «Try», чтобы провести тестирование, как показано на изображении выше, и мы получили следующий результат:
Возвращаемый результат содержит несколько полей, описание которых следующее:
  • solution, результат проверки после обработки изображения кода проверки hCaptcha.
    • label, содержимое, распознанное на изображении кода проверки hCaptcha.
    • box, информация о местоположении результата распознавания изображения кода проверки hCaptcha, которая состоит из координат изображения.
    • confidences, уровень уверенности в распознавании содержимого изображения кода проверки hCaptcha.
  • started_at, finished_at: время начала обработки текущего запроса и получения результата, Unix временная метка (секунды, с плавающей запятой).
  • elapsed: общее время обработки (в секундах).
Как видно, мы получили результат проверки изображения кода проверки hCaptcha, и нам нужно просто смоделировать клик по области, указанной координатами box в результате, чтобы пройти проверку. Далее будет описано, как кликнуть по координатам box в результате. Сначала создадим прямоугольную координатную систему для загруженного изображения кода проверки, где центр находится в левом нижнем углу изображения, 360 соответствует горизонтальной координате, а 276 — вертикальной координате. Нам нужно просто смоделировать клик по соответствующим координатам кода проверки, как показано на следующем изображении:

Если вы хотите сгенерировать соответствующий код интеграции, вы можете просто скопировать его, например, код CURL будет следующим:
Код интеграции на Python будет следующим:

​
Асинхронный режим (async)

По умолчанию API работает в синхронном блокирующем режиме: один запрос будет ждать, пока не завершится обработка результата распознавания. Если вы используете несколько ротаций кодировщиков (multi-solver rotation) и хотите «сразу получить task_id после отправки задачи, чтобы сначала распределить другие кодировщики, а затем вернуться за результатом», вы можете передать async: true в теле запроса. После передачи async: true интерфейс немедленно вернет task_id, не блокируя ожидание:
Если вы хотите активно отслеживать прогресс, вы можете использовать этот task_id для запроса POST /captcha/tasks (рекомендуется каждые 3~5 секунд). Этот интерфейс не будет инициировать или продвигать обработку задачи; даже если не запрашивать, отключить интернет или выйти из клиента, сервер продолжит обработку:
В процессе обработки будет возвращен status: processing:
После завершения обработки будет возвращен status: ready и результат распознавания solution (структура полей полностью совпадает с синхронным режимом):
Объяснение тарификации: в асинхронном режиме создание задачи и чтение статуса «в процессе» не тарифицируются; клиент будет тарифицирован один раз при первом успешном чтении результата (что соответствует существующему поведению и ценам синхронного режима). Сервер будет самостоятельно продвигать задачу, но не будет заранее списывать средства, если задача завершится в фоновом режиме. Если задача не будет успешно завершена в течение 120 секунд, она будет остановлена с HTTP 504 timeout, без тарификации. /captcha/tasks не отвечает за продвижение задач.

​
Обработка ошибок

При вызове API, если возникнет ошибка, API вернет соответствующий код ошибки и информацию. Например:
  • 400 token_mismatched: Неверный запрос, возможно, из-за отсутствующих или недействительных параметров.
  • 400 api_not_implemented: Неверный запрос, возможно, из-за отсутствующих или недействительных параметров.
  • 401 invalid_token: Неавторизован, недействительный или отсутствующий токен авторизации.
  • 429 too_many_requests: Слишком много запросов, вы превысили лимит частоты.
  • 500 api_error: Внутренняя ошибка сервера, что-то пошло не так на сервере.

​
Пример ответа об ошибке

​
Заключение

С помощью этого документа вы узнали, как использовать API распознавания изображений hCaptcha, чтобы пользователи могли вводить распознанное содержимое и изображение капчи hCaptcha, а затем возвращать координаты маленького изображения, на которое нужно нажать, для завершения проверки. Надеемся, что этот документ поможет вам лучше интегрировать и использовать этот API. Если у вас есть какие-либо вопросы, пожалуйста, не стесняйтесь обращаться в нашу техническую поддержку.