> ## 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 do rozpoznawania obrazów - instrukcja integracji > hCaptcha verification code recognition service API guide - Ace Data Cloud W tym artykule przedstawimy instrukcję integracji API do rozpoznawania obrazów hCaptcha, która pozwala na identyfikację treści wprowadzonych przez użytkownika oraz obrazów z kodem weryfikacyjnym hCaptcha, a na końcu zwraca współrzędne małego obrazu, który należy kliknąć, aby zakończyć weryfikację. ## Proces aplikacji Aby korzystać z API do rozpoznawania obrazów hCaptcha, najpierw przejdź do [konsoli Ace Data Cloud](https://platform.acedata.cloud/console/applications), aby uzyskać swój token API, który należy zachować na przyszłość. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na stronę logowania, aby zarejestrować się i zalogować, a po zakończeniu zostaniesz automatycznie przekierowany z powrotem na bieżącą stronę. **Jeden token API wystarczy do korzystania ze wszystkich usług platformy, nie ma potrzeby składania osobnych wniosków dla każdej usługi.** Przy pierwszym wniosku otrzymasz darmowy limit, aby móc go przetestować; w przypadku niewystarczającego limitu możesz doładować saldo ogólne w [konsoli](https://platform.acedata.cloud/console/coin). > 📘 Pełna dokumentacja: [API do rozpoznawania obrazów hCaptcha →](https://platform.acedata.cloud/documents/recognition-hcaptcha-integration) ## Podstawowe użycie Najpierw zapoznaj się z podstawowym sposobem użycia, polegającym na wprowadzeniu obrazu z kodem weryfikacyjnym hCaptcha, aby uzyskać przetworzony wynik. Najpierw musisz przekazać pole `queries`, które zawiera konkretny obraz z kodem weryfikacyjnym hCaptcha. Musimy zrzucić ten obraz z witryny z kodem weryfikacyjnym hCaptcha, przykładowy link do witryny to: `https://democaptcha.com/demo-form-eng/hcaptcha.html`, klikając pole wyboru, aby wyświetlić pełny obraz kodu weryfikacyjnego, jak pokazano na poniższym obrazku:

Pole `queries` to zrzut obrazu kodu weryfikacyjnego z powyższego tekstu, zaleca się, aby rozmiar obrazu nie przekraczał 100 kB. Należy również zrzucić obszar wskazany czerwoną strzałką na powyższym obrazie, a także samodzielnie skompresować rozmiar obrazu i przekonwertować go na kodowanie Base64, jak pokazano na poniższym obrazku:

Należy również wprowadzić parametr treści związany z obrazem kodu weryfikacyjnego `question`, który obsługuje tłumaczenie na język chiński i angielski. Można bezpośrednio wprowadzić odpowiednią treść, jak pokazano w żółtej strzałce na powyższym obrazie, `question` powinno być wprowadzone jako `Please click on the UNIQUE object among the others.`. Konkretna treść jest następująca:

Możemy zauważyć, że ustawiliśmy nagłówki żądania, w tym: * `accept`: jakiego formatu odpowiedzi oczekujesz, tutaj wpisujemy `application/json`, czyli format JSON. * `authorization`: klucz do wywołania API, po złożeniu wniosku można go bezpośrednio wybrać z rozwijanej listy. Dodatkowo ustawiono ciało żądania, w tym: * `queries`: lista obrazów kodu weryfikacyjnego zakodowanych w Base64. * `question`: parametr treści związany z obrazem kodu weryfikacyjnego, obsługujący bezpośrednie wprowadzanie w języku chińskim i angielskim. Po dokonaniu wyboru można zauważyć, że po prawej stronie wygenerowano odpowiedni kod, jak pokazano na poniższym obrazku:

Kliknij przycisk „Try”, aby przeprowadzić test, jak pokazano na powyższym obrazie, a otrzymamy następujący wynik: ```json theme={null} { "solution": { "label": "Please click on the UNIQUE object among the others", "box": [ "360", "276" ], "confidences": 0.6354503631591797 } } ``` Zwrócony wynik zawiera wiele pól, które są opisane poniżej: * `solution`, wynik weryfikacji po przetworzeniu zadania z obrazem kodu weryfikacyjnego hCaptcha. * `label`, treść rozpoznana na obrazie kodu weryfikacyjnego hCaptcha. * `box`, informacje o lokalizacji wyniku rozpoznawania obrazu kodu weryfikacyjnego hCaptcha, które składają się z informacji o współrzędnych obrazu. * `confidences`, poziom pewności rozpoznania treści na obrazie kodu weryfikacyjnego hCaptcha. Możemy zauważyć, że otrzymaliśmy wynik weryfikacji obrazu kodu weryfikacyjnego hCaptcha, wystarczy, że na podstawie informacji o współrzędnych `box` w wyniku symulujemy kliknięcie w ten obszar obrazu kodu weryfikacyjnego, aby przejść weryfikację. Poniżej przedstawimy, jak kliknąć na podstawie informacji o lokalizacji `box`. Najpierw tworzymy prostokątny układ współrzędnych dla przesłanego obrazu kodu weryfikacyjnego, gdzie środek układu znajduje się w lewym dolnym rogu obrazu, 360 to odpowiadająca współrzędna pozioma, a 276 to odpowiadająca współrzędna pionowa. Wystarczy, że symulujemy kliknięcie w odpowiednie współrzędne kodu weryfikacyjnego, jak pokazano na poniższym obrazie:

Jeśli chcesz wygenerować odpowiedni kod do integracji, możesz go bezpośrednio skopiować, na przykład kod CURL wygląda następująco: ```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"] }' ``` Kod do integracji w Pythonie wygląda następująco: ```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) ``` ## Tryb asynchroniczny (async) Domyślnie API działa w trybie synchronicznym: jedno żądanie będzie czekać, aż wynik rozpoznawania zostanie przetworzony, zanim zostanie zwrócone. Jeśli wykonujesz rotację wielu rozwiązań (multi-solver rotation) i chcesz „natychmiast uzyskać task\_id po złożeniu zadania, aby najpierw zlecić inne rozwiązania, a później wrócić po wyniki”, możesz przekazać `async: true` w ciele żądania. Po przekazaniu `async: true` interfejs natychmiast zwróci `task_id`, nie czekając na wynik: ```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": "przetwarzanie" } ``` Następnie użyj `task_id`, aby cyklicznie wywoływać `POST /captcha/tasks` (zaleca się co 3-5 sekund), aby uzyskać wyniki: ```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" }' ``` W trakcie przetwarzania zwróci `status: przetwarzanie`: ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "przetwarzanie" } ``` Po zakończeniu przetwarzania zwróci `status: gotowe` oraz wynik rozpoznawania `solution` (struktura pól jest całkowicie zgodna z trybem synchronicznym): ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "gotowe", "solution": { "label": "Proszę kliknąć na UNIKALNY obiekt wśród innych", "box": ["360", "276"], "confidences": 0.6354503631591797 } } ``` Opis rozliczeń: w trybie asynchronicznym, tworzenie zadań i cykliczne wywoływanie „przetwarzanie” nie jest obciążane opłatami; **opłata jest naliczana tylko raz, gdy uda się uzyskać wynik rozpoznawania** (cena jest zgodna z trybem synchronicznym). Dlatego anulowanie zadań, które nie zostały jeszcze zakończone, w trakcie cyklu nie generuje kosztów. `/captcha/tasks` jest wspólne dla wszystkich interfejsów CAPTCHA (token i seria rozpoznawania), wystarczy użyć tego samego `task_id` do cyklicznego wywoływania. ## Obsługa błędów Podczas wywoływania API, jeśli wystąpi błąd, API zwróci odpowiedni kod błędu i informacje. Na przykład: * `400 token_mismatched`: Złe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów. * `400 api_not_implemented`: Złe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów. * `401 invalid_token`: Nieautoryzowany, nieprawidłowy lub brakujący token autoryzacyjny. * `429 too_many_requests`: Zbyt wiele żądań, przekroczono limit szybkości. * `500 api_error`: Błąd wewnętrzny serwera, coś poszło nie tak na serwerze. ### Przykład odpowiedzi błędu ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "pobieranie nie powiodło się" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Wnioski Dzięki temu dokumentowi zrozumieli Państwo, jak korzystać z API rozpoznawania obrazów hCaptcha, aby umożliwić użytkownikom wprowadzenie rozpoznawanej treści oraz obrazu CAPTCHA hCaptcha, a na końcu zwrócić współrzędne małego obrazu, na który należy kliknąć, aby zakończyć weryfikację. Mamy nadzieję, że ten dokument pomoże Państwu lepiej zintegrować i korzystać z tego API. W razie jakichkolwiek pytań prosimy o kontakt z naszym zespołem wsparcia technicznego.