> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Travaux Asynchrones & Polling

> Créez des travaux médias asynchrones, interrogez l'état des tâches publiques de TokenLab et réconciliez les résultats finaux sans identifiants spécifiques au fournisseur.

De nombreux points de terminaison médias sont asynchrones. Une requête de création démarre le travail et renvoie une identité de tâche publique TokenLab ; votre application interroge jusqu'à ce que cette tâche atteigne un état terminal. Ne construisez pas les flux de travail des clients autour des URL de tâches en amont, des ID de routage ou du comportement de rappel du fournisseur.

## Contrat de Tâche Publique

Les réponses de création peuvent inclure :

| Champ      | Signification                                                  | Que faire                                                      |
| ---------- | -------------------------------------------------------------- | -------------------------------------------------------------- |
| `id`       | ID de tâche publique TokenLab                                  | Stockez-le avec votre propre enregistrement de travail         |
| `task_id`  | Alias de compatibilité pour la même identité de tâche publique | Traitez-le comme équivalent à `id`                             |
| `status`   | État actuel de la tâche publique                               | Commencez à interroger lorsqu'il n'est pas terminal            |
| `poll_url` | URL de statut préférée                                         | Utilisez ceci en premier lorsqu'il est présent                 |
| `model`    | Modèle demandé ou résolu par le point de terminaison           | Stockez-le pour la réconciliation de support et de facturation |

`/v1/tasks/{id}` est le point de terminaison d'état fixe canonique pour les travaux médias asynchrones publics. Des routes d'état spécifiques aux médias peuvent exister pour la compatibilité, mais les nouvelles intégrations devraient préférer `poll_url` ou `/v1/tasks/{id}`.

## Flux Recommandé

1. Validez la demande de l'utilisateur et envoyez l'appel de création avec un `model` explicite.
2. Persistez `id` / `task_id`, `poll_url`, point de terminaison, modèle, ID utilisateur et votre propre ID de travail avant de rendre le contrôle à l'UI.
3. Interrogez toutes les `5-10s` pour les tâches médias de longue durée.
4. Arrêtez-vous uniquement lorsque la tâche est `completed` ou `failed`.
5. Sur `completed`, lisez les champs de résultat spécifiques aux médias et stockez les URL finales ou les métadonnées.
6. Sur `failed`, stockez l'erreur publique et proposez une nouvelle tentative uniquement en tant que nouveau travail visible par l'utilisateur.

```json theme={null}
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "model": "veo3.1"
}
```

## Exemple de Polling

```bash theme={null}
curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"
```

Les états publics attendus sont `pending`, `processing`, `completed`, et `failed`. Les tâches annulées sont représentées comme `failed` avec `cancelled: true` et `cancellation_status: "cancelled"` afin que le traitement des anciens états continue de fonctionner.

## Règles de Réessai Client

Les délais d'attente réseau sont la source la plus courante de travaux en double. Utilisez cette règle :

| Où le délai d'attente se produit                           | Comportement plus sûr                                                                                   |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Avant que votre serveur ne reçoive une réponse de création | Vérifiez les journaux du serveur pour `request_id` ; réessayez uniquement si aucune tâche n'a été créée |
| Après qu'une réponse de création a été stockée             | Reprenez le polling du `task_id` stocké                                                                 |
| Pendant le polling                                         | Réessayez la demande de statut avec un backoff                                                          |
| Après un état terminal                                     | Ne polluez plus à moins que l'utilisateur ne rafraîchisse explicitement l'enregistrement                |

Ne pas envoyer une seconde requête de création simplement parce que le navigateur a été rafraîchi ou qu'un polling de statut a échoué.

## Facturation Et Règlement

Les travaux asynchrones peuvent réserver un montant estimé lorsque la requête de création est acceptée. Le règlement final se produit après l'état terminal. Lorsque disponible, les réponses d'état de tâche peuvent exposer `billing_transaction_id` et l'en-tête `X-Billing-Transaction-ID`.

Pour la réconciliation, joignez ces identifiants dans vos journaux :

* `request_id` de la requête de création.
* `task_id` / `id` de la tâche.
* `billing_transaction_id` lorsqu'il est présent.
* Votre propre ID utilisateur, ID de projet ou ID de travail.

## Annulation

`DELETE /v1/tasks/{id}` est intentionnellement étroit. Il prend actuellement en charge les tâches vidéo Volcengine Seedance en file d'attente telles que `seedance-1.5-pro`, `seedance-2.0`, et `seedance-2.0-fast`.

Les tâches non prises en charge renvoient `400 unsupported_task_cancel`. Les tâches qui sont déjà en cours d'exécution ou terminales renvoient `409 task_not_cancellable`. Construisez l'interface utilisateur d'annulation comme "demander l'annulation" plutôt qu'un bouton d'arrêt garanti.

## Dépannage

| Symptôme                              | Cause probable                                                                                           | Que vérifier                                                                                 |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `async_task_not_found`                | La tâche est inconnue, expirée, inaccessible à cette clé API, ou n'est pas une tâche asynchrone publique | Confirmez la propriété de la clé API et le `task_id` public stocké                           |
| La tâche ne semble jamais se terminer | Le client continue d'interroger la mauvaise URL ou s'est arrêté avant l'état terminal                    | Utilisez `poll_url` ou `/v1/tasks/{id}` et inspectez le dernier état                         |
| URL finale des médias manquante       | La tâche n'est pas terminée, ou le travail en amont s'est terminé sans sortie utilisable                 | Continuez à interroger jusqu'à l'état terminal, puis gérez la sortie manquante comme échouée |
| L'utilisateur voit des doublons       | Le chemin de réessai a créé une nouvelle tâche après un délai d'attente ou un rafraîchissement           | Dédupliquez par votre propre ID de travail et `task_id` stocké                               |
| Mismatch de facturation               | Le règlement est asynchrone ou le client compare des ID de fournisseur                                   | Comparez `request_id`, `task_id`, et `billing_transaction_id`                                |

## Paquet de Support

Lorsque vous contactez le support, incluez `request_id`, `task_id`, `billing_transaction_id` lorsqu'il est présent, point de terminaison, modèle, horodatage, et une forme de requête assainie. N'incluez pas de clés API, de médias privés, d'URLs signées, ou de prompts complets à moins que le support ne demande un échantillon expurgé.

## Référence API

| Sujet                      | Référence                                                             |
| -------------------------- | --------------------------------------------------------------------- |
| Obtenir l'état de la tâche | [Obtenir l'état de la tâche](/fr/api-reference/tasks/get-task-status) |
| Annuler la tâche           | [Annuler la tâche](/fr/api-reference/tasks/cancel-task)               |
| Génération d'images        | [Génération d'images](/fr/guides/image-generation)                    |
| Génération de vidéos       | [Génération de vidéos](/fr/guides/video-generation)                   |
| Génération de musique      | [Génération de musique](/fr/guides/music-generation)                  |
| Génération 3D              | [Génération 3D](/fr/guides/3d-generation)                             |
| Facturation & Tarification | [Facturation & Tarification](/fr/guides/billing)                      |