hCaptcha зображення розпізнавання API інтеграційна інструкція

Цей документ представить інтеграційну інструкцію для hCaptcha зображення розпізнавання API, яка може ідентифікувати вміст, введений користувачем, та зображення hCaptcha, а потім повернути координати малих зображень, на які потрібно натиснути, для завершення перевірки.

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

Щоб використовувати hCaptcha зображення розпізнавання API, спочатку перейдіть до консолі Ace Data Cloud для отримання вашого API Token, зберігши його для подальшого використання.

Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, запрошуючи вас зареєструватися та увійти, після чого ви будете автоматично повернені на поточну сторінку. Один API Token дозволяє викликати всі послуги платформи, без необхідності окремої заявки для кожної послуги. Перший запит на отримання токена надає безкоштовний ліміт, щоб ви могли безкоштовно протестувати; якщо ліміт вичерпано, ви можете поповнити загальний баланс на консолі.

📘 Повна документація: hCaptcha зображення розпізнавання API →

Основне використання

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

Після вибору ви можете помітити, що праворуч також згенеровано відповідний код, як показано на малюнку:

Натисніть кнопку «Спробувати», щоб провести тестування, як показано на малюнку, тут ми отримали наступний результат:

{
  "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.
started_at, finished_at: час початку обробки запиту та отримання результату, Unix-мітка часу (секунди, з плаваючою комою).
elapsed: загальний час обробки (секунди).

Ми отримали результат перевірки зображення hCaptcha, нам потрібно лише натиснути на область зображення коду відповідно до координат інформації box, щоб пройти перевірку. Далі буде описано, як натиснути на основі інформації про позицію box. Спочатку потрібно створити прямокутну координатну систему для завантаженого зображення коду, де центр координат знаходиться в нижньому лівому куті зображення, 360 - це відповідна горизонтальна координата, 276 - відповідна вертикальна координата, нам потрібно просто натиснути на координати, що відповідають коду, як показано на малюнку нижче:

Крім того, якщо ви хочете згенерувати відповідний код інтеграції, ви можете безпосередньо скопіювати його, наприклад, код CURL виглядає так:

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 виглядає так:

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, не блокуючи очікування:

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
}'

{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}

Якщо потрібно активно перевірити прогрес, можна використовувати цей task_id для запиту POST /captcha/tasks (рекомендується кожні 3~5 секунд). Цей інтерфейс не викликає або не просуває обробку завдання; навіть якщо не запитувати, відключити інтернет або вийти з клієнта, сервер все ще продовжить обробку:

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:

{ "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "processing" }

Після завершення обробки буде повернуто status: ready та результат розпізнавання solution (структура полів повністю відповідає синхронному режиму):

{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "solution": {
    "label": "Будь ласка, натисніть на УНІКАЛЬНИЙ об'єкт серед інших",
    "box": ["360", "276"],
    "confidences": 0.6354503631591797
  }
}

Опис тарифікації: в асинхронному режимі створення завдання та читання статусу «в обробці» не тарифікуються; клієнт сплачує один раз при першому успішному читанні результату (згідно з існуючою поведінкою та ціною синхронного режиму). Сервер самостійно просуває завдання, але не буде знімати плату за завершення в бекграунді. Якщо завдання не буде успішно завершено протягом 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: Внутрішня помилка сервера, щось пішло не так на сервері.

Приклад відповіді на помилку

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Висновок

Завдяки цьому документу, ви вже зрозуміли, як використовувати API розпізнавання зображень hCaptcha, щоб користувач вводив розпізнані дані та зображення капчі hCaptcha, а в кінці повертати координати маленького зображення, на яке потрібно натиснути, для завершення перевірки. Сподіваємося, цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

Ідентичність

Проксі

Advanced

Coding

hCaptcha зображення розпізнавання API інтеграційна інструкція

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

Основне використання

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

Обробка помилок

Приклад відповіді на помилку

Висновок

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

​Основне використання

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

​Обробка помилок

​Приклад відповіді на помилку

​Висновок

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

Основне використання

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

Обробка помилок

Приклад відповіді на помилку

Висновок