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

# API для запроса задач CAPTCHA (асинхронные задачи на сервере)

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

В этом документе описан интерфейс запроса асинхронных задач CAPTCHA `POST /captcha/tasks`. Когда вы вызываете любой интерфейс CAPTCHA (серия токенов или серия распознавания) с параметром `async: true`, интерфейс немедленно возвращает `task_id`, сервер сразу берет на себя обработку и продолжает ее; вы можете использовать этот `task_id` для запроса окончательного результата, но запрос не является условием для продолжения выполнения задачи. Подходит для сценариев с ротацией многократных решателей (multi-solver rotation): после отправки задачи вы сразу получаете `task_id`, сначала можете задействовать других решателей, а позже вернуться и прочитать результат.

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

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

Чтобы использовать этот интерфейс, сначала перейдите в [консоль Ace Data Cloud](https://platform.acedata.cloud/console/applications) и получите ваш API Token для резервного копирования. **Одного API Token достаточно для вызова всех сервисов платформы, не нужно запрашивать отдельный для каждого сервиса.**

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

### Шаг 1: Создание задачи асинхронным способом

В теле запроса любого интерфейса CAPTCHA передайте `async: true`, интерфейс немедленно вернет `task_id` (HTTP 201), не блокируя ожидание:

```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}
{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}
```

### Шаг 2 (необязательно): Запрос результата с помощью task\_id

Если необходимо активно отслеживать прогресс, вы можете использовать `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` и соответствующие поля результата — структура полей полностью совпадает с синхронным режимом:

* **серия токенов** (hcaptcha, recaptcha2, recaptcha3) возвращает `token`:

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

* **категория распознавания** (recognition/recaptcha2, recognition/hcaptcha) возвращает `solution`; **recognition/image2text** возвращает `text`.

`/captcha/tasks` универсален для всех интерфейсов CAPTCHA (серии токенов и распознавания), можно использовать один и тот же `task_id` для опроса.

Сервер продолжает обработку с момента создания, максимальное время 120 секунд. Если при последнем запросе к дедлайну результат все еще не получен, будет возвращен HTTP 504. Этот статус является конечным, клиент должен прекратить опрос; повторные запросы одного и того же `task_id` будут стабильно возвращать одинаковый результат ошибки:

```json theme={null}
{
  "detail": "The captcha task timed out.",
  "code": "timeout",
  "success": false,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "failed",
  "started_at": 1784885653.0,
  "finished_at": 1784885765.4,
  "elapsed": 112.4
}
```

Ответы с `status: ready` и HTTP 504 будут содержать временные поля.

* `started_at`, время начала обработки задачи, Unix временная метка (секунды, с плавающей точкой).
* `finished_at`, время получения результата задачи, Unix временная метка (секунды, с плавающей точкой). Это поле не возвращается, если задача все еще обрабатывается.
* `elapsed`, время обработки задачи, в секундах (с плавающей точкой, с 3 знаками после запятой). Это поле не возвращается, если задача все еще обрабатывается.

## Условия оплаты

В асинхронном режиме создание задачи и чтение состояния "в процессе" не подлежат оплате; **клиент оплачивает один раз при первом успешном чтении результата** (в соответствии с существующим поведением и ценами синхронного режима). Сервер будет самостоятельно продвигать задачу, но не будет взимать плату заранее, если задача завершится в фоновом режиме. Задачи, не завершившиеся успешно в течение 120 секунд, будут завершены с HTTP 504 и не подлежат оплате.

## Обработка ошибок

При вызове этого интерфейса, если возникнет ошибка, будет возвращен соответствующий код ошибки и информация. Например:

* `400 invalid_request`: запрос не содержит параметра `task_id`.
* `401 invalid_token`: несанкционированный доступ, токен авторизации недействителен или отсутствует.
* `404 not_found`: `task_id` не существует или не принадлежит текущему аккаунту.
* `504 timeout`: задача была завершена и не дала результата; пожалуйста, прекратите опрос этого `task_id`. Эта ошибка не приведет к оплате.

### Пример ответа об ошибке

```json theme={null}
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "task not found"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.