> ## 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 Протокол Распознавания API Инструкция по интеграции

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

В данной статье будет представлена инструкция по интеграции API распознавания протокола Recaptcha2, которая позволяет пользователям не распознавать и не нажимать на изображения капчи Recaptcha2, а просто отправить Website Key для автоматической декодировки на сервере и завершения проверки.

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

Чтобы использовать API распознавания протокола Recaptcha2, сначала перейдите в [консоль 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).

> 📘 Полная документация: [API распознавания протокола Recaptcha2 →](https://platform.acedata.cloud/documents/captcha-token-recaptcha2)

## Основное использование

Сначала ознакомьтесь с основным способом использования, который заключается в вводе URL сайта, на котором нужно обработать капчу, чтобы получить обработанный результат. Сначала необходимо просто передать поле `website_url`, наш пример сайта: `https://www.google.com/recaptcha/api2/demo`, нам нужно получить `website_key` на странице `website_url`, для этого откройте эту веб-страницу, нажмите F12 для входа в консоль, а затем выполните глобальный поиск по элементам на странице `recaptcha-demo`, мы можем получить следующий результат:

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

Где строка, соответствующая `data-sitekey`, является значением `website_key`, ниже приведены конкретные параметры результата:

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

Как видно, здесь мы установили заголовки запроса, включая:

* `accept`: формат ответа, который вы хотите получить, здесь указано `application/json`, то есть формат JSON.
* `authorization`: ключ для вызова API, после подачи заявки его можно выбрать из выпадающего списка.

Также установлен Body запроса, включая:

* `website_url`: URL сайта, на котором нужно обработать капчу.
* `website_key`: идентификатор сайта в Recaptcha2.

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

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

Нажмите кнопку «Попробовать», чтобы провести тестирование, как показано на изображении выше, здесь мы получили следующий результат:

```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"
}
```

Результат содержит несколько полей, описание которых приведено ниже:

* `token`, результат проверки после обработки задачи Recaptcha2.

Можно увидеть, что мы получили результат проверки Recaptcha2, который затем можно использовать для POST-запроса или имитации отправки на целевой сайт, одноразового использования, срок действия 120 секунд, рекомендуется использовать в течение 60 секунд. Далее будет предоставлен фрагмент на Python, который отправляет обработанный токен на целевой сайт для прохождения проверки Recaptcha2.

Сначала нам нужно выяснить, как сайт отправляет POST-запрос, чтобы мы могли передать сгенерированный токен. Для этого нам нужно открыть консоль F12, затем вручную пройти проверку, в конце мы увидим, что сайт отправил POST-запрос. Нам нужно только посмотреть, как был построен этот POST-запрос, конкретный процесс выглядит следующим образом:

* Сначала вручную пройти проверку, конкретно как на изображении ниже:

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

* Затем нажать на submit, наблюдая за изменениями в сети консоли, конкретно как на изображении ниже:

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

* Проанализировать структуру отправленного POST-запроса, в конце можно щелкнуть правой кнопкой мыши на этом запросе и скопировать код CURL, конкретно как на изображении ниже:

<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。如有任何问题，请随时联系我们的技术支持团队。