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

# Verifieringskodens uppgiftssökning API (server-sidans asynkrona uppgifter) integrationsbeskrivning

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

Denna artikel beskriver verifieringskodens asynkrona uppgiftssökningsgränssnitt `POST /captcha/tasks`. När du anropar valfritt verifieringskodgränssnitt (token-serien eller recognition-serien) och skickar in `async: true`, kommer gränssnittet omedelbart att returnera ett `task_id`, servern kommer omedelbart att ta över och fortsätta bearbeta; du kan använda detta `task_id` för att fråga om det slutliga resultatet, men att fråga är inte en förutsättning för att uppgiften ska fortsätta att köras. Lämplig för scenarier som multi-solver rotation: efter att ha skickat in uppgiften får du omedelbart `task_id`, först schemalägger du andra verifieringskodlösare och återkommer senare för att läsa resultatet.

> 📘 Fullständig interaktiv dokumentation (inklusive online-testning): [Verifieringskodens uppgiftssökning API →](https://platform.acedata.cloud/documents/captcha-tasks)

## Ansökningsprocess

För att använda detta gränssnitt, gå först till [Ace Data Cloud-konsolen](https://platform.acedata.cloud/console/applications) för att hämta din API-token, som du kan spara som reserv. **En API-token kan anropas för alla plattformens tjänster, det behövs ingen separat ansökan för varje tjänst.**

## Grundläggande användning

### Steg ett: Skapa uppgift asynkront

I begärans kropp för valfritt verifieringskodgränssnitt, skicka in `async: true`, gränssnittet kommer omedelbart att returnera `task_id` (HTTP 201) utan att blockera väntan:

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

### Steg två (valfritt): Fråga resultat med task\_id

Om du vill se framstegen aktivt kan du använda det `task_id` som returnerades i föregående steg för att fråga `POST /captcha/tasks` (rekommenderas var 3-5 sekund). Detta gränssnitt kommer inte att utlösa eller påskynda uppgiftens bearbetning; när du läser det färdiga resultatet följer det den befintliga engångsavräkningsbeteendet:

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

Under bearbetning kommer det att returnera `status: processing`:

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

När bearbetningen är klar kommer det att returnera `status: ready` och motsvarande resultatfält - fältstrukturen är helt identisk med den synkrona modellen:

* **token-serien** (hcaptcha, recaptcha2, recaptcha3) returnerar `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-kategorin** (recognition/recaptcha2, recognition/hcaptcha) returnerar `solution`; **recognition/image2text** returnerar `text`.

`/captcha/tasks` är gemensam för alla verifieringskodgränssnitt (token- och recognition-serier), du kan använda samma `task_id` för att göra polling.

Servern fortsätter att bearbeta från skapandet och längst upp till 120 sekunder. Om den sista frågan vid deadline fortfarande inte har fått något resultat kommer den att returnera HTTP 504. Detta tillstånd är ett slutligt tillstånd, klienten bör sluta pollinga; att upprepade gånger fråga samma `task_id` kommer stabilt att returnera samma misslyckade resultat:

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

Både `status: ready` och HTTP 504:s slutliga svar kommer att ha tidsfält.

* `started_at`, tidpunkten då uppgiften började bearbetas, Unix-tidsstämpel (sekunder, flyttal).
* `finished_at`, tidpunkten då uppgiften producerade resultat, Unix-tidsstämpel (sekunder, flyttal). Detta fält returneras inte när den fortfarande är under bearbetning.
* `elapsed`, tiden som uppgiften tog att bearbeta, enhet i sekunder (flyttal, behåll 3 decimaler). Detta fält returneras inte när den fortfarande är under bearbetning.

## Avgiftsbeskrivning

I asynkront läge debiteras inte skapandet av uppgifter och läsning av "under bearbetning"-status; **klienten debiteras en gång när den första framgångsrika resultatet läses** (samma som befintligt beteende och priser för synkron modell). Servern kommer att driva uppgiften själv, men kommer inte att debitera i förväg bara för att bakgrunden slutfördes först. Uppgifter som inte lyckas inom 120 sekunder deadline avslutas med HTTP 504 och debiteras inte.

## Felhantering

När du anropar detta gränssnitt, om du stöter på fel, kommer det att returnera motsvarande felkod och information. Till exempel:

* `400 invalid_request`: Begäran saknar `task_id`-parameter.
* `401 invalid_token`: Ej auktoriserad, auktoriseringstoken ogiltig eller saknas.
* `404 not_found`: `task_id` finns inte eller tillhör inte det aktuella kontot.
* `504 timeout`: Uppgiften har avslutats och har inte producerat resultat; vänligen sluta pollinga detta `task_id`. Detta misslyckande kommer inte att debiteras.

### Exempel på felrespons

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