> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # hCaptcha изображение распознавания API интеграция > hCaptcha verification code recognition service API guide - Ace Data Cloud В этой статье будет представлено руководство по интеграции hCaptcha изображения распознавания API, которое может идентифицировать содержимое, введенное пользователем, и изображение hCaptcha, а затем вернуть координаты маленького изображения, на которое нужно кликнуть, чтобы завершить проверку. ## Процесс подачи заявки Чтобы использовать hCaptcha изображение распознавания API, сначала перейдите в [консоль Ace Data Cloud](https://platform.acedata.cloud/console/applications), чтобы получить ваш API Token и сохранить его для использования. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Если вы еще не вошли в систему или не зарегистрированы, вы будете автоматически перенаправлены на страницу входа, где вас пригласят зарегистрироваться и войти. После завершения вы будете автоматически возвращены на текущую страницу. **Один API Token позволяет вызывать все услуги платформы, не нужно отдельно запрашивать для каждой услуги.** При первом запросе предоставляется бесплатный лимит, чтобы вы могли попробовать бесплатно; если лимит исчерпан, вы можете пополнить общий баланс в [консоли](https://platform.acedata.cloud/console/coin). > 📘 Полная документация: [hCaptcha изображение распознавания API →](https://platform.acedata.cloud/documents/recognition-hcaptcha-integration) ## Основное использование Сначала ознакомьтесь с основным способом использования, который заключается в том, чтобы ввести изображение 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», чтобы провести тестирование, как показано на изображении выше, и мы получили следующий результат: ```json theme={null} { "solution": { "label": "Please click on the UNIQUE object among the others", "box": [ "360", "276" ], "confidences": 0.6354503631591797 } } ``` Возвращаемый результат содержит несколько полей, описание которых приведено ниже: * `solution`, результат проверки после обработки задачи изображения hCaptcha. * `label`, содержимое, распознанное на изображении hCaptcha. * `box`, информация о местоположении результата распознавания изображения hCaptcha, которая состоит из координат изображения. * `confidences`, степень уверенности в распознавании содержимого после распознавания изображения hCaptcha. Как видно, мы получили результат проверки изображения hCaptcha, и нам нужно просто смоделировать клик по области, указанной координатами `box`, чтобы пройти проверку. Далее будет описано, как кликнуть по координатам, указанным в `box`. Сначала создадим прямоугольную координатную систему для загруженного изображения кода проверки, где центр находится в левом нижнем углу изображения, 360 соответствует горизонтальной координате, а 276 — вертикальной. Нам нужно просто смоделировать клик по соответствующим координатам кода проверки, как показано на следующем изображении:

Если вы хотите сгенерировать соответствующий код интеграции, вы можете просто скопировать его, например, код CURL выглядит следующим образом: ```shell theme={null} 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 выглядит следующим образом: ```python theme={null} 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) ``` ## Асинхронный режим (async) По умолчанию API работает в синхронном блокирующем режиме: один запрос будет ждать, пока не завершится обработка результата распознавания. Если вы используете несколько ротаций кодов (multi-solver rotation) и хотите «сразу получить task\_id после отправки задачи, чтобы сначала переключиться на другие коды, а затем вернуться за результатом», вы можете передать `async: true` в теле запроса. После передачи `async: true` интерфейс сразу вернет `task_id`, не блокируя ожидание: ```shell theme={null} 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"], "async": true }' ``` ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab", "status": "processing" } ``` Затем используйте этот `task_id` для опроса `POST /captcha/tasks` (рекомендуется каждые 3\~5 секунд) для получения результата: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/captcha/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002" }' ``` В процессе обработки будет возвращен `status: processing`: ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "processing" } ``` После завершения обработки будет возвращен `status: ready` и результат распознавания `solution` (структура полей полностью совпадает с синхронным режимом): ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "ready", "solution": { "label": "Пожалуйста, нажмите на УНИКАЛЬный объект среди других", "box": ["360", "276"], "confidences": 0.6354503631591797 } } ``` Условия оплаты: в асинхронном режиме создание задачи и опрос «в процессе обработки» не облагаются платой; **плата взимается только один раз при успешном получении результата распознавания** (цена такая же, как в синхронном режиме). Поэтому отмена незавершенных задач в процессе опроса не приведет к расходам. `/captcha/tasks` универсален для всех интерфейсов CAPTCHA (серии token и recognition), можно использовать один и тот же `task_id` для опроса. ## Обработка ошибок При вызове API, если возникла ошибка, API вернет соответствующий код ошибки и информацию. Например: * `400 token_mismatched`: Неверный запрос, возможно, из-за отсутствующих или недействительных параметров. * `400 api_not_implemented`: Неверный запрос, возможно, из-за отсутствующих или недействительных параметров. * `401 invalid_token`: Неавторизован, недействительный или отсутствующий токен авторизации. * `429 too_many_requests`: Слишком много запросов, вы превысили лимит частоты. * `500 api_error`: Внутренняя ошибка сервера, что-то пошло не так на сервере. ### Пример ответа об ошибке ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "не удалось получить" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Заключение С помощью этого документа вы узнали, как использовать API распознавания изображений hCaptcha, чтобы пользователи могли вводить распознанное содержимое и изображение CAPTCHA hCaptcha, а в конце возвращать координаты маленького изображения, на которое нужно нажать, для завершения проверки. Надеемся, что этот документ поможет вам лучше интегрировать и использовать этот API. Если у вас есть какие-либо вопросы, пожалуйста, не стесняйтесь обращаться в нашу техническую поддержку.