> ## 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 de requête de tâche de captcha (tâche asynchrone côté serveur) Documentation d'intégration

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

Cet article présente l'interface de requête de tâche de captcha asynchrone `POST /captcha/tasks`. Lorsque vous appelez n'importe quelle interface de captcha (série token ou série reconnaissance) en passant `async: true`, l'interface renverra immédiatement un `task_id`, le serveur prendra immédiatement en charge et continuera à traiter ; vous pouvez utiliser ce `task_id` pour interroger le résultat final, mais l'interrogation n'est pas une condition préalable à l'exécution continue de la tâche. Cela convient à des scénarios tels que la rotation de plusieurs solveurs (multi-solver rotation) : après avoir soumis la tâche, vous obtenez immédiatement le `task_id`, vous pouvez d'abord planifier d'autres solveurs, puis revenir plus tard pour lire les résultats.

> 📘 Documentation interactive complète (avec débogage en ligne) : [API de requête de tâche de captcha →](https://platform.acedata.cloud/documents/captcha-tasks)

## Processus de demande

Pour utiliser cette interface, rendez-vous d'abord sur le [tableau de bord Ace Data Cloud](https://platform.acedata.cloud/console/applications) pour obtenir votre API Token, à conserver en réserve. **Un API Token suffit pour appeler tous les services de la plateforme, il n'est pas nécessaire de demander un pour chaque service.**

## Utilisation de base

### Étape 1 : Créer une tâche de manière asynchrone

Dans le corps de la requête de n'importe quelle interface de captcha, passez `async: true`, l'interface renverra immédiatement un `task_id` (HTTP 201), sans bloquer l'attente :

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

### Étape 2 (facultatif) : Interroger le résultat avec task\_id

Si vous souhaitez vérifier activement l'avancement, vous pouvez utiliser le `task_id` renvoyé à l'étape précédente pour interroger `POST /captcha/tasks` (il est conseillé de le faire toutes les 3 à 5 secondes). Cette interface ne déclenchera ni n'avancera le traitement de la tâche ; la lecture des résultats prêts suivra le comportement de règlement unique existant :

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

En cours de traitement, cela renverra `status: processing` :

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

Une fois le traitement terminé, cela renverra `status: ready` et le champ de résultat correspondant — la structure des champs est complètement identique à celle du mode synchrone :

* **série token** (hcaptcha, recaptcha2, recaptcha3) renvoie `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......"
}
```

* **classification de reconnaissance** (recognition/recaptcha2, recognition/hcaptcha) renvoie `solution` ; **recognition/image2text** renvoie `text`.

`/captcha/tasks` est commun à toutes les interfaces de captcha (séries token et reconnaissance), vous pouvez interroger avec le même `task_id`.

Le serveur continue de traiter depuis sa création, pendant un maximum de 120 secondes. Si lors de la dernière interrogation avant la date limite, aucun résultat n'est obtenu, cela renverra un HTTP 504. Cet état est terminal, le client doit arrêter l'interrogation ; interroger plusieurs fois le même `task_id` renverra de manière stable le même résultat d'échec :

```json theme={null}
{
  "detail": "La tâche de captcha a expiré.",
  "code": "timeout",
  "success": false,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "failed",
  "started_at": 1784885653.0,
  "finished_at": 1784885765.4,
  "elapsed": 112.4
}
```

Les réponses terminales `status: ready` et HTTP 504 incluront également des champs de chronométrage.

* `started_at`, heure de début du traitement de la tâche, horodatage Unix (secondes, flottant).
* `finished_at`, heure de production du résultat de la tâche, horodatage Unix (secondes, flottant). Ce champ ne sera pas renvoyé tant que le traitement est en cours.
* `elapsed`, temps de traitement de la tâche, en secondes (flottant, avec 3 décimales). Ce champ ne sera pas renvoyé tant que le traitement est en cours.

## Informations de facturation

En mode asynchrone, la création de tâches et la lecture de l'état "en cours de traitement" ne sont pas facturées ; **le client est facturé une fois lors de la première lecture réussie des résultats** (identique au comportement existant et au prix du mode synchrone). Le serveur fera avancer la tâche de manière autonome, mais ne facturera pas à l'avance en raison d'une fin de traitement en arrière-plan. Les tâches qui n'ont pas réussi dans les 120 secondes de délai seront terminées par un HTTP 504 et ne seront pas facturées.

## Gestion des erreurs

Lors de l'appel de cette interface, si une erreur se produit, un code d'erreur et un message appropriés seront renvoyés. Par exemple :

* `400 invalid_request` : la requête manque du paramètre `task_id`.
* `401 invalid_token` : non autorisé, le token d'autorisation est invalide ou manquant.
* `404 not_found` : `task_id` n'existe pas ou n'appartient pas au compte actuel.
* `504 timeout` : la tâche a été terminée et n'a pas produit de résultat ; veuillez arrêter l'interrogation de ce `task_id`. Cet échec ne sera pas facturé.

### Exemple de réponse d'erreur

```json theme={null}
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "tâche non trouvée"
  }
}
```


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