> ## 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 do zapytania o zadania CAPTCHA (asynchroniczne zadania serwera)

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

Niniejszy dokument opisuje interfejs zapytania o asynchroniczne zadania CAPTCHA `POST /captcha/tasks`. Gdy wywołujesz dowolny interfejs CAPTCHA (seria tokenów lub seria rozpoznawania) z parametrem `async: true`, interfejs natychmiast zwraca `task_id`, a serwer przejmuje i kontynuuje przetwarzanie; możesz użyć tego `task_id`, aby sprawdzić ostateczny wynik, ale zapytanie nie jest warunkiem kontynuacji zadania. Odpowiednie do scenariuszy rotacji wielu rozwiązywaczy (multi-solver rotation): po złożeniu zadania natychmiast otrzymujesz `task_id`, a następnie możesz zlecić inne rozwiązywacze, a później wrócić, aby odczytać wyniki.

> 📘 Pełna interaktywna dokumentacja (w tym online debugging): [API do zapytania o zadania CAPTCHA →](https://platform.acedata.cloud/documents/captcha-tasks)

## Proces aplikacji

Aby skorzystać z tego interfejsu, najpierw przejdź do [konsoli Ace Data Cloud](https://platform.acedata.cloud/console/applications), aby uzyskać swój token API, który należy zachować na przyszłość. **Jeden token API wystarczy do wywołania wszystkich usług platformy, nie ma potrzeby składania osobnych wniosków dla każdej usługi.**

## Podstawowe użycie

### Krok pierwszy: utworzenie zadania w trybie asynchronicznym

W ciele żądania dowolnego interfejsu CAPTCHA przekaż `async: true`, a interfejs natychmiast zwróci `task_id` (HTTP 201), nie blokując oczekiwania:

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

### Krok drugi (opcjonalny): zapytanie o wynik za pomocą task\_id

Jeśli chcesz aktywnie sprawdzić postęp, możesz użyć `task_id` zwróconego w poprzednim kroku, aby zapytać `POST /captcha/tasks` (zaleca się co 3-5 sekund). Ten interfejs nie uruchomi ani nie przyspieszy przetwarzania zadania; odczytując gotowy wynik, zachowaj istniejące zachowanie jednorazowego rozliczenia:

```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 trakcie przetwarzania zwróci `status: processing`:

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

Po zakończeniu przetwarzania zwróci `status: ready` oraz odpowiednie pola wynikowe — struktura pól jest całkowicie zgodna z trybem synchronizacji:

* **seria tokenów** (hcaptcha, recaptcha2, recaptcha3) zwraca `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......"
}
```

* **klasyfikacja rozpoznawania** (recognition/recaptcha2, recognition/hcaptcha) zwraca `solution`; **recognition/image2text** zwraca `text`.

`/captcha/tasks` jest uniwersalne dla wszystkich interfejsów CAPTCHA (seria tokenów i rozpoznawania), wystarczy użyć tego samego `task_id` do zapytań.

Serwer kontynuuje przetwarzanie od momentu utworzenia, maksymalnie przez 120 sekund. Jeśli podczas ostatniego zapytania przed upływem terminu nadal nie uzyskano wyniku, zwróci HTTP 504. Ten status jest stanem końcowym, klient powinien zaprzestać zapytań; powtarzające się zapytania o ten sam `task_id` będą stabilnie zwracać ten sam wynik błędu:

```json theme={null}
{
  "detail": "Zadanie CAPTCHA przekroczyło czas oczekiwania.",
  "code": "timeout",
  "success": false,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "failed",
  "started_at": 1784885653.0,
  "finished_at": 1784885765.4,
  "elapsed": 112.4
}
```

Zarówno odpowiedzi z `status: ready`, jak i HTTP 504 będą zawierać pola czasowe.

* `started_at`, czas rozpoczęcia przetwarzania zadania, znacznik czasu Unix (sekundy, liczba zmiennoprzecinkowa).
* `finished_at`, czas uzyskania wyniku zadania, znacznik czasu Unix (sekundy, liczba zmiennoprzecinkowa). Nie jest zwracane, gdy nadal jest w trakcie przetwarzania.
* `elapsed`, czas przetwarzania zadania, jednostka to sekundy (liczba zmiennoprzecinkowa, z dokładnością do 3 miejsc po przecinku). Nie jest zwracane, gdy nadal jest w trakcie przetwarzania.

## Informacje o opłatach

W trybie asynchronicznym, tworzenie zadań i odczytywanie statusu „w trakcie przetwarzania” nie są obciążane opłatami; **klient jest obciążany jednorazowo przy pierwszym odczycie udanego wyniku** (zgodnie z istniejącym zachowaniem i cenami w trybie synchronizacji). Serwer samodzielnie przyspiesza zadania, ale nie obciąży opłatami, jeśli zadanie zakończy się w tle. Zadania, które nie zakończą się pomyślnie w ciągu 120 sekund, są kończone z HTTP 504 i nie są obciążane opłatami.

## Obsługa błędów

Podczas wywoływania tego interfejsu, jeśli wystąpią błędy, zwróci odpowiedni kod błędu i informacje. Na przykład:

* `400 invalid_request`: Żądanie brakuje parametru `task_id`.
* `401 invalid_token`: Brak autoryzacji, token autoryzacyjny jest nieprawidłowy lub brakujący.
* `404 not_found`: `task_id` nie istnieje lub nie należy do bieżącego konta.
* `504 timeout`: Zadanie zostało zakończone i nie wygenerowało wyniku; proszę zaprzestać zapytań o ten `task_id`. Ta awaria nie będzie obciążana opłatami.

### Przykład odpowiedzi błędu

```json theme={null}
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "zadanie nie znalezione"
  }
}
```


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