> ## 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 для запиту завдань з перевірочним кодом (асинхронні завдання на сервері)

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

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

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

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

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

## Основне використання

### Перший крок: створення завдання асинхронно

У тілі запиту до будь-якого інтерфейсу перевірочного коду передайте `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"
}
```

### Другий крок (необов'язковий): запит результату за допомогою 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` є універсальним для всіх інтерфейсів перевірочного коду (серії токенів та розпізнавання), можна використовувати один і той же `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.