> ## 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.

# Recaptcha2 Protokoll Erkennungs-API Integrationsanleitung

> Recaptcha verification code recognition service API guide - Ace Data Cloud

Dieser Artikel beschreibt eine Integrationsanleitung für die Recaptcha2 Protokoll Erkennungs-API, die es Benutzern ermöglicht, die Recaptcha2 Verifizierungscode-Bilder nicht zu erkennen und auszuwählen, sondern lediglich durch die Einreichung des Website-Schlüssels eine automatische Dekodierung im Hintergrund zu erreichen und die Verifizierung abzuschließen.

## Antragsprozess

Um die Recaptcha2 Protokoll Erkennungs-API zu nutzen, 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: [Recaptcha2 Protokoll Erkennungs-API →](https://platform.acedata.cloud/documents/captcha-token-recaptcha2)

## Grundlegende Nutzung

Zunächst sollten Sie die grundlegende Nutzung verstehen, indem Sie die URL der Website eingeben, die den zu verarbeitenden Verifizierungscode enthält, um das verarbeitete Ergebnis zu erhalten. Zuerst müssen Sie einfach ein `website_url`-Feld übermitteln. Unsere Beispielwebsite ist: `https://www.google.com/recaptcha/api2/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 Element-Bereich global nach `recaptcha-demo`, um das folgende Ergebnis zu erhalten:

<p>
  <img src="https://cdn.acedata.cloud/hvx41c.png" width="500" className="m-auto" />
</p>

Die `data-sitekey`-Zeichenfolge entspricht dem Wert des `website_key`, hier sind die spezifischen Parameterergebnisse:

<p>
  <img src="https://cdn.acedata.cloud/8oowyw.png" width="500" className="m-auto" />
</p>

Hier haben wir die Request-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 Request-Body festgelegt, einschließlich:

* `website_url`: Die URL der Website, die den Verifizierungscode verarbeitet.
* `website_key`: Der Website-Schlüssel-Identifikator in Recaptcha2.

Nach der Auswahl können Sie feststellen, dass auf der rechten Seite auch der entsprechende Code generiert wurde, wie im Bild gezeigt:

<p>
  <img src="https://cdn.acedata.cloud/pudujk.png" width="500" className="m-auto" />
</p>

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": "03AFcWeA5kjJyDQ9S1a9UYimR6nuxnpEnAs5x2Pixao0dXZhMBjiR2MwAwN7K3NXik02Vl--cEmCwxDuf7mNBMbGlfLHb5948cvCdk1jnp_mjbWzT9ZyxzSnny52TiWVZo1xvTTad5QIQz9iRfJrjcM1BkBj5OpwT4mRVK-Yoz8Q8m5MlXEwQ5Zyp0Lxh_L-32EkdwyyCIOlG-Q1wJ-lR7utNB6E8MCrtTM1tox75-3KPvMNHbTjvqSf1l3FO_bASk39mtleI_NjThAPHCBL__cHu2wJxRYITYxqYgCu3FYcmC3OfcUJJEmgg4KEpQTIjo1X2N1m81obHWKrOrrNqfQvELnXrhHU4gVcFwpaMladoLysqOrDqHsYxNeUTp5YiEu6_Xl2eC6r9IKTbeddIf5QXQML_OILc4Ee3-vEUepmelWq7GE4wOKf8zQ8Xfz1MbJM3daEmiVEMFs4EQsjGgioPeyQUjiJT5U2sZfiJbgyGdUVletCBn4abnSLBYVI-rKKlETKu4IQVGCmh_hNn7cnkX3E5p_Kqu3gifOYHSbCu2ctuaPe9G3M8XxbQ57b_UFgg1MMToSAcZDL2NWtL4yPag5Y4lCnpmfrGOwvX-QFF0JF-DrbRn_Opv52JrLD9GrfGxo99kiucQIZkAzpWLV3Kkhtep2DB8OiA4rSb5R6xT4nNoawg1BM2cM5jazL-1U6LzSs9Hq1XWV1nwj-8-mTDwHmBYMI6fmSfl1-bOX0uHGgWHnzEAW2mw4EErVVUTUJJcUr_LZ2woRkexk-CPQTtdlHmQHbt_1FsOzfGtnXY87xIbhCJReVyv-_HQ48d9xCDuQ-JnNjX98NfDsfvpxe9Zar_LjcQCBNtvHgKH_JkniBDiWrZBAoDJIonDjJ6X1mmWLyPDxYmBR6O7QkxR3DxdDvZQRaZnfD-_sA9T9JEkYWHdBlpumEBq9wVs8dSm60TiRAOZU1ZLjieGP5vI5_aV-ct5SwOmWHF-VQkJUfNZ33MoEkZW2Rvh7_ERbI_PRS_u65BCkhuOh8fmQcxJU5YACpoLXXkwGM8qmSB1yBBeOQL-wWUfo8GREpZIu1oGQVQ8k3FcNJzFQQAYcLBWfGn-8qMxfAJEd356lJYIUuU1CY2rhR1u_7C1R_bH0WTifDqYLCRGzn-tzqBOXybrkOs_KURL-gT6wAoZRpUvBBAEa1mRg5gxap0pOkpdf7MPb5PsWVME7E3stvordioyN2tdLKr6VC-0kiQZD1WzykazPZzkl302Y_kpQ2vKPawWVWmNhy5Vm_cwT6afOAuSHnU1aYtFNvEDpBcXXH2YcqS-sBnMb3KlO5KpfZSp-tGzvjds46ajyoD7bHGzxvCx9EplICVrGWQ8gRYe2MCVJ3OocE-VK7PxI1iKXJK_LBl4hQR7uUKaDVEbmBYMcgS1z5YmXbJV89yjrU-u5ncTn5JkJgoSdOvMi8l2fsZIl2wYi-hWgQjP6LLI6M6wr8AhyiSZBQ34adR07niQPzLfX5Ntwr_8NyMg69bWKlLXknv8O2KznYXQQwsWA3okJCGwhfJkp35QnkHsprTN9LD48cwg8zP7a1mgM-2WHuZmoCpqg1XJgT_tPjc7X9kCQt8e3YirW6IJs-CdBUDkbp12FCukip48mDz7SOWjnLruoNABfo_zCurdOQY_tfcWe4g_ef0y_vey3hLGvxuay_ZMGzDLIo-7_WEp7jU09YKqWOZV7cSxDPm65M1v69ND6b5awsopISEe7E3hKMGrVSonRa9_bkiQ2fuPa5-xitNr4IMxwWMepqDk54v_cyVzUBdAAq8V8w3VHvV4-tjTXFqp0L54RBhJ_EaCXO7nwNbVLqCirfDpKRASfkYoaqsoXbwFMpfFrh-KzDZVIuU6D-VBF5k50ufGPnoXTA8kIF0GjAepW5SCxYupoQos4La6W2f--cl4WAl8oKhSpFtRpb1CNMKmtD7_BJrPDxpnXiA-ENBFe8Y4EOoG5uavVeQl6YftHej52JOTKurOqD-NE-UDBLInNuOo0ayCdV1w8XDAnORgxbkYP65GO5FdytK4zrDVNQEK26D54e0xLpDqUG8UUmUT_VNj9UY78WyWGPTXiGwYAA2_iVUKbT8-phHLDDqeoG3Q5iTP7RUpaW49JmM-tlSeczqqyy9Wc8iZh2Cf9veRJ7HiUeIEMeKGnqD7E9nXxcjC75GzIo477c83U7QN_1QXQjWuAr0C3KFq2W7dJmO08pQ0Z13dG7tz4Ilg1Bc3LIcNgeJLkCTZYpDpn7JpeZRbe6fqvmbqWPQ"
}
```

Die Rückgabe enthält mehrere Felder, die wie folgt beschrieben werden:

* `token`, das Ergebnis der Verarbeitung der Recaptcha2-Verifizierung.

Man kann sehen, dass wir das Ergebnis der Verarbeitung der Recaptcha2-Verifizierung erhalten haben, das wir dann für POST oder zur Simulation der Einreichung an die Zielwebsite verwenden können, einmalig nutzbar, mit einer Gültigkeitsdauer von 120 Sekunden, empfohlen innerhalb von 60 Sekunden zu verwenden. Im Folgenden wird ein Python-Skript bereitgestellt, um das verarbeitete Token an die Zielwebsite zu übermitteln, um die Recaptcha2-Verifizierung zu bestehen.

Zuerst müssen wir herausfinden, wie die Website POST-Anfragen sendet, damit wir das generierte Token einfügen können. Wir müssen zunächst die F12-Konsole öffnen und manuell eine Überprüfung durchführen. Schließlich können wir sehen, dass die Website eine POST-Anfrage gesendet hat. Wir müssen nur die Struktur dieser POST-Anfrage überprüfen. Der genaue Prozess ist wie folgt:

* Zuerst manuell die Überprüfung durchführen, wie im folgenden Bild gezeigt:

<p>
  <img src="https://cdn.acedata.cloud/gwiflr.png" width="500" className="m-auto" />
</p>

* Dann auf "submit" klicken und die Änderungen im Netzwerk der Konsole beobachten, wie im folgenden Bild gezeigt:

<p>
  <img src="https://cdn.acedata.cloud/6hm5kj.png" width="500" className="m-auto" />
</p>

* Analysieren Sie die Struktur der gesendeten POST-Anfrage und kopieren Sie den CURL-Code dieser Anfrage mit der rechten Maustaste, wie im folgenden Bild gezeigt:

<p>
  <img src="https://cdn.acedata.cloud/m7y35w.png" width="500" className="m-auto" />
</p>

由上图分析可知，此次POST请求的URL为：`https://www.google.com/recaptcha/api2/demo`，我们仅需要提交参数 `g-recaptcha-response`，然后我们只需要将处理后的token传入下面的data中即可，调用token进行验证的具体的CURL代码如下：

```shell theme={null}
curl 'https://www.google.com/recaptcha/api2/demo' \
  --data-raw 'g-recaptcha-response={token}’
```

调用token验证所对应的Python代码如下：

```python theme={null}
import requests

token = '{token}'

data = {
    'g-recaptcha-response': token,
}

response = requests.post('https://www.google.com/recaptcha/api2/demo',data=data)

if response.status_code:
    print(response.text)

```

然后我们运行后代码观察控制台变得了这样的结果：

<p>
  <img src="https://cdn.acedata.cloud/ku22tk.png" width="500" className="m-auto" />
</p>

最后我们就通过了Recaptcha2验证码的协议验证。

另外如果想生成对应的对接代码，可以直接复制生成，例如 CURL 的代码如下：

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/token/recaptcha2' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_key": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
  "website_url": "https://www.google.com/recaptcha/api2/demo"
}'
```

Python 的对接代码如下：

```python theme={null}
import requests

url = "https://api.acedata.cloud/captcha/token/recaptcha2"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "website_key": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    "website_url": "https://www.google.com/recaptcha/api2/demo"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

## 异步模式（async）

默认情况下 API 是同步阻塞的：一次请求会一直等待，直到 token 处理完成才返回。如果你在做多打码器轮换（multi-solver rotation），希望「提交任务后立即拿到 task\_id，先去调度其他打码器，稍后再回来取结果」，可以在请求体中传入 `async: true`。

传入 `async: true` 后，接口会立即返回一个 `task_id`，而不会阻塞等待：

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/token/recaptcha2' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_key": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
  "website_url": "https://www.google.com/recaptcha/api2/demo",
  "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` 和 token：

```json theme={null}
{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "token": "03AFcWeA5kjJyDQ9S1a9UYimR6nuxnpEnAs5x2Pixao0dXZhMB......"
}
```

计费说明：异步模式下，创建任务与轮询「处理中」都不计费；**仅在成功取到结果时计费一次**（与同步模式的价格一致）。因此在轮换中取消尚未完成的任务不会产生费用。`/captcha/tasks` 对所有验证码接口（token 与 recognition 系列）通用，用同一个 `task_id` 轮询即可。

## 错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：

* `400 token_mismatched`：Bad request, possibly due to missing or invalid parameters.
* `400 api_not_implemented`：Bad request, possibly due to missing or invalid parameters.
* `401 invalid_token`：Unauthorized, invalid or missing authorization token.
* `429 too_many_requests`：Too many requests, you have exceeded the rate limit.
* `500 api_error`：Internal server error, something went wrong on the server.

### 错误响应示例

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

## 结论

通过本文档，您已经了解了如何使用 Recaptcha2 协议识别 API 让用户无需识别和点选 Recaptcha2 验证码图片，仅需通过提交 Website Key 即可实现后台自动解码，完成验证。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。