> ## 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 Protokoll Erkennungs-API Integrationsanleitung > hCaptcha verification code recognition service API guide - Ace Data Cloud Dieser Artikel beschreibt eine hCaptcha Protokoll Erkennungs-API Integrationsanleitung, die es Benutzern ermöglicht, hCaptcha Verifizierungscodes ohne Erkennung und Auswahl der Bilder zu übermitteln, sondern lediglich durch die Einreichung des Website-Schlüssels die automatische Dekodierung im Hintergrund zu erreichen und die Verifizierung abzuschließen. ## Antragsprozess Um die hCaptcha Protokoll Erkennungs-API zu verwenden, müssen Sie zunächst im [Ace Data Cloud Dashboard](https://platform.acedata.cloud/console/applications) Ihr API-Token abrufen und für zukünftige Verwendung aufbewahren. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, die Sie zur Registrierung und Anmeldung einlädt. Nach Abschluss werden Sie automatisch zur aktuellen Seite zurückgeleitet. **Ein API-Token reicht aus, um alle Dienste der Plattform zu nutzen, es ist nicht erforderlich, für jeden Dienst separat zu beantragen.** Bei der ersten Beantragung erhalten Sie ein kostenloses Kontingent, um es kostenlos auszuprobieren; wenn das Kontingent nicht ausreicht, können Sie im [Dashboard](https://platform.acedata.cloud/console/coin) Ihr allgemeines Guthaben aufladen. > 📘 Vollständige Dokumentation: [hCaptcha Protokoll Erkennungs-API →](https://platform.acedata.cloud/documents/captcha-token-hcaptcha) ## Grundlegende Nutzung Zunächst sollten Sie die grundlegende Nutzung verstehen, indem Sie die URL der Website eingeben, die das hCaptcha zu verarbeiten hat, um das verarbeitete Ergebnis zu erhalten. Zuerst müssen Sie einfach ein `website_url` Feld übermitteln. Unsere Beispielwebsite ist: `https://accounts.hcaptcha.com/demo`, wir müssen auf der `website_url` Seite den `website_key` abrufen. Öffnen Sie zunächst diese Webseite, drücken Sie F12, um die Konsole zu öffnen, und suchen Sie dann im Elementbereich global nach `hcaptcha-demo`, um die folgenden Ergebnisse zu erhalten:

Die Zeichenfolge, die dem `data-sitekey` entspricht, ist der Wert des `website_key`. Hier sind die spezifischen Parameterergebnisse:

Hier haben wir die Anfrage-Header festgelegt, einschließlich: * `accept`: In welchem Format Sie die Antwort erhalten möchten, hier eingetragen als `application/json`, also im JSON-Format. * `authorization`: Der Schlüssel zur API-Nutzung, den Sie nach der Beantragung direkt auswählen können. Zusätzlich haben wir den Anfrage-Body festgelegt, einschließlich: * `website_url`: Die URL der Website, die den Verifizierungscode verarbeiten muss. * `website_key`: Der Website-Schlüsselidentifikator in hCaptcha. Nach der Auswahl können Sie feststellen, dass auf der rechten Seite auch der entsprechende Code generiert wurde, wie im Bild gezeigt:

Klicken Sie auf die Schaltfläche „Try“, um einen Test durchzuführen. Wie im obigen Bild gezeigt, haben wir das folgende Ergebnis erhalten: ```json theme={null} { "token": "P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.hadwYXNza2V5xQda4nQzFgUbYJqILiiwbvyhjocSilg8RjFHvIHmCzmqUNZa9hesIWEVRx5KIbMVeAQzSTWCwXmiQrPZuIEmZz-ZPL6DPNmB3ZXtJNsVYRLdRyvWPTB7EYskJG85yDVor2TcgQFNqAahhKT3WXjtk3S54ZBhv7QvaImUmos8MWgUOvUZHsvUtojN-izWIrBkD1if_71quOHvcvEVTLcSLx9dOgzpNAJ8_6BmJEsGlPbMGnSKrS1QfpPyzvgrnpjjIY_6TMYwJrR0EwJgCdp_lfc4mkxl0NJsZt8D_q7jcv3v6jt1CZ2qbqF5_-i4y0MYnQMCm1T62xBPdiEyst_FtGuWxJllkrrmWN0edyWcWeasLcCS6qpRry0H7RU7DYQnML6dmQoZg15NT0tFrAYeLK7EwvJxzcFbvUQ-Tc5QVk7tzvKpDtUVfQeZmRRgxWbCFf6bAT1z0uUwdma1O1lcTkSZCC5cVTaprkkKE04Ov4aCIKg2N7WGj4r0AOykisAISX5oidF3gejDTJy9vU1hgaCYFOimnwRKyqRsJdznptzhzDOQuICuAHYT3is1sY26ltJGOZTdDKkt2i2owCoAylgLbBP8VjTOGrsM12IH3Xsy076O40RCG6zThWN5TFKSpl7PNA6l2KoW-P3_K9WORjx2DSvKTAwqcouSU-0Rc_8Hlq9cIuS1iDhiNfJnJ_zNy_2gXSR2j7NP7m_lsfwELKypKm6pPzIhOuz5RwPotfPQfXOMdF3Xy98iQiihZmuHENvLAhjV_W7NL9TK3THPwDTFriS8ghIncl02v-fVARXDiuFTvjjlegL7xbHgIrOhLpunsxLiwdImUWatEI9jqaf84X4BtoS0TGYo4pHkpIG10dhoz3vooeSToAws6tz7ZWSHm6naksZ41X_WIxd7N8P9yzxrbLgVv-nHia5qHQLDmiZf3alITKhtisennw8NpespaQIVZzw_B16bdUNKqHCCTLdFbr16-3KpRoHzOOU2kBhV-gDN0NiA3ecqIMnyMdnpKlUpnjJ5sMA3e0pKEX_Vbu8DE8zfkcwLIwCIb2BLrKEHnCvv4JX8TfBktzMc5oTtZyEu-E_6ew0mSm_nhVsGtmLXSsB81FP9VGGRd50buIXRNW4GFp3XdTmYyuN32kc-AHJ5kKDj2HGraHxKco0McT7nV2bgx97k-C7hgxL2x5t3lC97edphh2kt2-gXuTxxfB7K-ZG6w5d1MnRte4ZG7TxvPFFi5693IFRFbvcr-U3WyGZJmGGdfV55PnoIU9Qn-WDtBU4EXyvd_KTt-asHtI6VQiVSNzacemTfsu9WBF33f2gafDY4qqhyXDPNsu6BZCGMSBhxDPURY74OBr4mYOdhjELY07nSkr9RQtQwiiSa8B8XFlezCPafjgdbmmNzG3PXa3n23sSwVnJHpHhq79eTP_KeeCiqlCvNsHLEfiH5HCNRGp7v5b342wBk__BWFimJMvohz0rucTVYgVFBdTOomUTuqCPeUgDP3X6BnNqyVDRA-HrdRl-RkU6mnw-3-IwyMZQ-fEnFMzbGp3zaoY7Do2jKvKKILoq6Q8zlDYkrLwuXjDP-nernI2hxP9wVOUVmtq5Rs19RLUI4MNWZAqwG-wGnaoB756d8nfmh5XhFzvArE5bpL50FY1yJqv7nbPW7JNnkfZG80yVRrIZO_F9NEb3n4eiIzg9Gu9fv8ncyChiCCp-swK5B7_w-XsAlco98bO-YK-fFMJOhyt0PU8Zc-hYoCa6cLVTvhdPzIUA0CQOemg4Pz6PX6SVwLYSlOXYkzbrgBlyH5YBS3oaRCeavVLrJsKt0_KwHwgBa1mdP5mlYUpBDbKR4PKwknU7y111JH0B4fO39dOVA-zecvDG0bnuy98Jym4KUchZr1tXabMcM20mg1UvcxMfnKOx0ojBcVwYA7kPQK3EzMnwX9NbAzYP6IlMgjFK9ZM7HCXxN6J1_6kw10RT4O58-Pbh3cMSrZDfM-GuG7p7XrVpJrX8TD195DCJqx-DmVv3Bs3CiuCPTvGrSZ58KE4hQagidGreUD2WXxLBFfTv1RgM3eXMtROs7hddyBajIu401lxucNbpRB7lYV7pJwxG7LQoSZ2G2LzG8eFPVPIkDNVOa8nGzh-sWaF7kc7bVv-P4FXbLX0WCjvQRES2MCbXPyJ-OpZZXZcJy7SOsGY3jZbTkGoez19cRQLiFO35gA5l9FBptDKW-_yGemt5XeKsR_FwGPN9C-0k1E-28oB4iKo-h1zb2kJpilhnmG36Z59F5T6W77M7OD_N6VHRWuPClLElO09OrPLHbJmxq9JvMWjTg5JjEaqyTLyLXWgw0N3kZMCqJJeqNj5w5I7dpuJ6ScfXKVaT96v2UESebdbMFT7vkZAkFF8LIowkN56pNwXLHkB2KyIWR2WQL-335BEpQ0AVB6RX4kdociIhtvAdsIE6pvFIwkzyO0OvIHxzOwPxZKdmDmBVMu7YxJStrhY-XWCu4kO5gDIJ0iedPWKNleHDOZuZqGKhzaGFyZF9pZM4xrUyBomtyqDE1ZmUwNDhkonBkAA.dVWyVc6N3lx2ZJQ7NJ9aEsWA-KAIuQ4PMSKVGQuWyCA" } ``` 可以看到我们得到了处理 hCaptcha验证码 的验证结果，然后我们可以用于POST或模拟提交给目标网站，一次性使用，有效期120s，建议在60s内使用，接下来将提供一段CURL版本将处理后token提交到目标网站来通过Recaptcha2验证码。 首先我们需要获取网站是如何发送POST请求，这样我们才能将生成的token传入进去，我们需要先打开F12控制台，然后人工先通过一下，最后我们可以看到网站发送了一个POST请求，我们只需要查看这次的POST请求构造，具体的过程如下： * 先人工通过验证，具体的如下图：

* 再点击submit，观看控制台的network变化，具体的如下图：

* 分析此次提交的POST请求构造，最后可以右键该请求复制CURL的代码，具体的如下图：

由上图分析可知，此次POST请求的URL为：`https://accounts.hcaptcha.com/demo`，我们仅需要提交参数 `g-recaptcha-response`、`h-captcha-response` 和 `email`，然后我们只需要将处理后的token传入下面的data中即可，调用token验证所对应CURL代码如下： ```shell theme={null} curl 'https://accounts.hcaptcha.com/demo' \ --data-raw 'email=&g-recaptcha-response={token}&h-captcha-response={token}' ``` 调用token验证所对应的Python代码如下： ```python theme={null} import requests token = '{token}' data = { 'email': '', 'g-recaptcha-response': token, 'h-captcha-response': token } response = requests.post('https://accounts.hcaptcha.com/demo', data=data) if response.status_code == 200: print(response.text) ``` 然后我们观察控制台变得了这样的结果：

最后我们就通过了hCaptcha验证码的验证。 另外如果想生成对应的对接代码，可以直接复制生成，例如 CURL 的代码如下： ```shell theme={null} curl -X POST 'https://api.acedata.cloud/captcha/token/hcaptcha' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "website_key": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2", "website_url": "https://accounts.hcaptcha.com/demo" }' ``` Python 的对接代码如下： ```python theme={null} import requests url = "https://api.acedata.cloud/captcha/token/hcaptcha" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "website_key": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2", "website_url": "https://accounts.hcaptcha.com/demo" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ## 异步模式（async） 标准mäßig ist die API synchron blockierend: Eine Anfrage wartet, bis die Tokenverarbeitung abgeschlossen ist, bevor sie zurückgegeben wird. Wenn Sie eine Multi-Solver-Rotation durchführen und „nach dem Einreichen der Aufgabe sofort die task\_id erhalten möchten, um andere Solver zu planen und später das Ergebnis abzurufen“, können Sie `async: true` im Anfragekörper übergeben. Nach der Übergabe von `async: true` gibt die Schnittstelle sofort eine `task_id` zurück, ohne zu blockieren: ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab", "status": "processing" } ``` Verwenden Sie dann diese `task_id`, um `POST /captcha/tasks` abzufragen (empfohlen alle 3-5 Sekunden), um das Ergebnis zu erhalten: ```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ährend der Verarbeitung wird `status: processing` zurückgegeben: ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "processing" } ``` Nach Abschluss der Verarbeitung wird `status: ready` und das Token zurückgegeben: ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "ready", "token": "P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1Ni......" } ``` Abrechnungsinformationen: Im asynchronen Modus werden die Erstellung von Aufgaben und die Abfrage „in Bearbeitung“ nicht berechnet; **es wird nur einmal berechnet, wenn das Token erfolgreich abgerufen wird** (zum gleichen Preis wie im synchronen Modus). Daher entstehen beim Abbrechen von noch nicht abgeschlossenen Aufgaben in der Rotation keine Kosten. `/captcha/tasks` ist für alle CAPTCHA-Schnittstellen (Token und Erkennungsserien wie hcaptcha, recaptcha2, recaptcha3, recognition/\* usw.) allgemein und kann mit derselben `task_id` abgefragt werden. ## Fehlerbehandlung Wenn beim Aufrufen der API ein Fehler auftritt, gibt die API den entsprechenden Fehlercode und die Fehlermeldung zurück. Zum Beispiel: * `400 token_mismatched`: Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter. * `400 api_not_implemented`: Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter. * `401 invalid_token`: Unbefugt, ungültiger oder fehlender Autorisierungstoken. * `429 too_many_requests`: Zu viele Anfragen, Sie haben das Kontingent überschritten. * `500 api_error`: Interner Serverfehler, etwas ist auf dem Server schiefgelaufen. ### Fehlerantwort Beispiel ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Fazit Durch dieses Dokument haben Sie gelernt, wie Sie die hCaptcha-Protokoll-Identifikations-API verwenden, damit Benutzer die hCaptcha-Bilder nicht erkennen und anklicken müssen, sondern einfach den Website-Schlüssel einreichen können, um die automatische Dekodierung im Hintergrund durchzuführen und die Überprüfung abzuschließen. Wir hoffen, dass dieses Dokument Ihnen hilft, die API besser zu integrieren und zu verwenden. Bei Fragen wenden Sie sich bitte jederzeit an unser technisches Support-Team.