> ## 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 zur Abfrage von Captcha-Aufgaben (Server-seitige asynchrone Aufgaben) Integrationsanleitung

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

Dieser Artikel beschreibt die API zur Abfrage von asynchronen Captcha-Aufgaben `POST /captcha/tasks`. Wenn Sie bei der Verwendung einer beliebigen Captcha-Schnittstelle (Token-Serie oder Erkennungsserie) `async: true` übergeben, gibt die Schnittstelle sofort eine `task_id` zurück, der Server übernimmt sofort und verarbeitet weiter; Sie können diese `task_id` verwenden, um das endgültige Ergebnis abzufragen, aber die Abfrage ist nicht die Voraussetzung für die Fortsetzung der Aufgabenbearbeitung. Dies ist geeignet für Szenarien wie Multi-Solver-Rotation: Nachdem Sie die Aufgabe eingereicht haben, erhalten Sie sofort die `task_id`, um andere Solver zu planen und später zurückzukehren, um die Ergebnisse abzurufen.

> 📘 Vollständige interaktive Dokumentation (einschließlich Online-Debugging): [API zur Abfrage von Captcha-Aufgaben →](https://platform.acedata.cloud/documents/captcha-tasks)

## Antragsprozess

Um diese Schnittstelle zu verwenden, gehen Sie zuerst zur [Ace Data Cloud-Konsole](https://platform.acedata.cloud/console/applications), um Ihr API-Token zu erhalten, das Sie als Reserve aufbewahren. **Ein API-Token kann alle Dienste der Plattform aufrufen, es ist nicht erforderlich, für jeden Dienst separat zu beantragen.**

## Grundlegende Verwendung

### Schritt 1: Aufgabe asynchron erstellen

Übergeben Sie in der Anfrage an eine beliebige Captcha-Schnittstelle `async: true`, die Schnittstelle gibt sofort eine `task_id` zurück (HTTP 201), ohne zu blockieren und zu warten:

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

### Schritt 2 (optional): Ergebnisse mit task\_id abfragen

Wenn Sie den Fortschritt aktiv überprüfen möchten, können Sie die in Schritt 1 zurückgegebene `task_id` verwenden, um `POST /captcha/tasks` abzufragen (empfohlen alle 3-5 Sekunden). Diese Schnittstelle löst oder beschleunigt die Aufgabenbearbeitung nicht; beim Abrufen der bereitstehenden Ergebnisse wird das bestehende einmalige Abrechnungsverhalten beibehalten:

```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ährend der Verarbeitung wird `status: processing` zurückgegeben:

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

Nach Abschluss der Verarbeitung wird `status: ready` und das entsprechende Ergebnisfeld zurückgegeben – die Feldstruktur ist identisch mit der im synchronen Modus:

* **Token-Serie** (hcaptcha, recaptcha2, recaptcha3) gibt `token` zurück:

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

* **Erkennungs-Kategorie** (recognition/recaptcha2, recognition/hcaptcha) gibt `solution` zurück; **recognition/image2text** gibt `text` zurück.

`/captcha/tasks` ist für alle Captcha-Schnittstellen (Token- und Erkennungsserie) allgemein und kann mit derselben `task_id` abgefragt werden.

Der Server verarbeitet kontinuierlich ab dem Zeitpunkt der Erstellung, maximal 120 Sekunden. Wenn bei der letzten Abfrage vor Ablauf der Frist noch kein Ergebnis vorliegt, wird HTTP 504 persistiert. Dieser Status ist der Endstatus, der Client sollte die Abfrage einstellen; wiederholte Abfragen derselben `task_id` geben stabil dasselbe Fehlermeldungsergebnis zurück:

```json theme={null}
{
  "detail": "Die Captcha-Aufgabe ist abgelaufen.",
  "code": "timeout",
  "success": false,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "failed",
  "started_at": 1784885653.0,
  "finished_at": 1784885765.4,
  "elapsed": 112.4
}
```

Sowohl die Antwort mit `status: ready` als auch die HTTP 504-Endstatusantwort enthalten Zeitstempelfelder.

* `started_at`, Zeitpunkt des Beginns der Aufgabenbearbeitung, Unix-Zeitstempel (Sekunden, Fließkomma).
* `finished_at`, Zeitpunkt der Ergebnisproduktion der Aufgabe, Unix-Zeitstempel (Sekunden, Fließkomma). Wird während der Verarbeitung nicht zurückgegeben.
* `elapsed`, Zeitaufwand für die Aufgabenbearbeitung, Einheit in Sekunden (Fließkomma, auf 3 Dezimalstellen gerundet). Wird während der Verarbeitung nicht zurückgegeben.

## Abrechnungsinformationen

Im asynchronen Modus werden die Erstellung von Aufgaben und das Abrufen des „Verarbeitungs“-Status nicht abgerechnet; **der Client wird einmal abgerechnet, wenn das erste erfolgreiche Ergebnis abgerufen wird** (entspricht dem bestehenden Verhalten und den Preisen im synchronen Modus). Der Server wird die Aufgaben selbstständig vorantreiben, aber es wird keine vorzeitige Abrechnung erfolgen, nur weil die Verarbeitung im Hintergrund abgeschlossen ist. Aufgaben, die innerhalb von 120 Sekunden nicht erfolgreich sind, werden mit HTTP 504 beendet und nicht abgerechnet.

## Fehlerbehandlung

Wenn beim Aufruf dieser Schnittstelle ein Fehler auftritt, wird der entsprechende Fehlercode und die Fehlermeldung zurückgegeben. Zum Beispiel:

* `400 invalid_request`: Anfrage fehlt den Parameter `task_id`.
* `401 invalid_token`: Unautorisiert, der Autorisierungstoken ist ungültig oder fehlt.
* `404 not_found`: `task_id` existiert nicht oder gehört nicht zum aktuellen Konto.
* `504 timeout`: Die Aufgabe wurde beendet und hat kein Ergebnis produziert; bitte stoppen Sie die Abfrage dieser `task_id`. Dieser Fehler wird nicht abgerechnet.

### Beispiel für eine Fehlerantwort

```json theme={null}
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Aufgabe nicht gefunden"
  }
}
```


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