Travaux Asynchrones & Polling

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é

Validez la demande de l’utilisateur et envoyez l’appel de création avec un model explicite.
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.
Interrogez toutes les 5-10s pour les tâches médias de longue durée.
Arrêtez-vous uniquement lorsque la tâche est completed ou failed.
Sur completed, lisez les champs de résultat spécifiques aux médias et stockez les URL finales ou les métadonnées.
Sur failed, stockez l’erreur publique et proposez une nouvelle tentative uniquement en tant que nouveau travail visible par l’utilisateur.

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "model": "veo3.1"
}

Exemple de Polling

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
Annuler la tâche	Annuler la tâche
Génération d’images	Génération d’images
Génération de vidéos	Génération de vidéos
Génération de musique	Génération de musique
Génération 3D	Génération 3D
Facturation & Tarification	Facturation & Tarification

​Contrat de Tâche Publique

​Flux Recommandé

​Exemple de Polling

​Règles de Réessai Client

​Facturation Et Règlement

​Annulation

​Dépannage

​Paquet de Support

​Référence API