> ## 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`: параметр вмісту, пов'язаний із зображенням коду, підтримує безпосередній ввід на китайській та англійській мовах. Після вибору ви також можете помітити, що праворуч згенеровано відповідний код, як показано на малюнку:

Натисніть кнопку «Спробувати», щоб провести тестування, як показано на малюнку, і ми отримали наступний результат: ```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": "обробка" } ``` Потім використовуйте цей `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: обробка`: ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "обробка" } ``` Після завершення обробки буде повернуто `status: готово` та результат розпізнавання `solution` (структура полів повністю збігається з синхронним режимом): ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "готово", "solution": { "label": "Будь ласка, натисніть на УНІКАЛЬНИЙ об'єкт серед інших", "box": ["360", "276"], "confidences": 0.6354503631591797 } } ``` Опис плати: в асинхронному режимі створення завдання та опитування «обробка» не підлягає оплаті; **лише при успішному отриманні результату розпізнавання стягується плата один раз** (ціна така ж, як у синхронному режимі). Тому скасування незавершених завдань під час обертання не призведе до витрат. `/captcha/tasks` є загальним для всіх інтерфейсів перевірки CAPTCHA (серії токенів та розпізнавання), можна використовувати один і той же `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. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.