TokenLab

Guides essentiels

Tâches asynchrones et polling

Créez des tâches multimédias et attendez le résultat final

De nombreux endpoints multimédias renvoient une tâche au lieu d'un fichier finalisé. Enregistrez l'ID de tâche renvoyé et effectuez un polling sur GET /v1/tasks/{id} jusqu'à ce que le statut soit completed ou failed. Ce endpoint unique prend en charge les tâches d'image, de vidéo, de musique, de 3D, de Worlds et de transcription audio asynchrone.

Les snapshots de tâches terminales asynchrones ont un cycle de vie distinct de la fenêtre de capture de 30 jours des requêtes/réponses. Les URLs des fichiers générés (image, vidéo, audio, 3D et Worlds) sont des URLs de résultats multimédias TokenLab qui restent valides pendant 30 jours. La lecture du statut des tâches terminées fonctionne pendant environ 7 jours ; enregistrez donc le résultat dès que la tâche est terminée. Les champs media_retention de la réponse indiquent le statut de sauvegarde de chaque élément ainsi que sa date d'expiration (expires_at) ; ils peuvent être absents si le statut de sauvegarde n'est pas connu à temps, bien que l'URL fonctionne toujours. Les tâches échouées ou en cours renvoient des champs d'URL multimédia vides. Voir Rétention des données.

Champs à enregistrer

Les réponses de création peuvent inclure :

ChampSignificationAction à effectuer
idID de tâche TokenLabStockez-le avec votre propre enregistrement de travail
task_idAutre nom pour le même ID de tâcheTraitez-le comme équivalent à id
statusStatut actuel de la tâcheContinuez à vérifier jusqu'à ce qu'elle soit terminée ou échouée
poll_urlURL de statut de la tâcheStockez-la ; effectuez un polling sur /v1/tasks/{id} avec l'ID de tâche
modelModèle utilisé pour la tâcheStockez-le avec l'enregistrement de la tâche

Un endpoint de statut unique

Effectuez un polling sur GET /v1/tasks/{id} avec l' id ou le task_id provenant de la réponse de création. Cela fonctionne pour tous les types de tâches. Pour la plupart des tâches, poll_url correspond à ce même chemin. Une réponse de création Worlds renvoie une poll_url sous /v1/worlds/generations/{id} ; effectuez également le polling sur /v1/tasks/{id} avec l' id de tâche pour Worlds.

Les chemins de statut par modalité, tels que /v1/videos/generations/{id}, restent pris en charge pour les intégrations existantes. Les nouvelles intégrations doivent utiliser /v1/tasks/{id}.

Enregistrer la tâche et vérifier son statut

Enregistrez l' id ou le task_id dès que la requête de création réussit. Stockez avec lui l' poll_url, le modèle, le endpoint, ainsi que votre propre ID utilisateur ou ID de travail. Pour les tâches multimédias longues, une vérification toutes les 5 à 10 secondes est généralement suffisante.

Arrêtez-vous lorsque le statut devient completed ou failed. Une tâche terminée contient le résultat multimédia ; une tâche échouée contient l'erreur que vous pouvez afficher ou consigner. Réessayer une génération échouée crée une nouvelle tâche et peut entraîner une nouvelle facturation.

{
  "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 statuts sont pending, processing, completed et failed. Une tâche annulée utilise failed avec cancelled: true et cancellation_status: "cancelled".

Une lecture de statut réussie renvoie HTTP 200 même lorsque la tâche a échoué. Utilisez le status de la tâche pour déterminer si la génération a réussi. Le champ error conserve sa forme de chaîne ou d'objet. Les tâches échouées peuvent également inclure error_details avec status (le statut d'erreur métier), type, code, message, param et retryable. Par exemple, error_details.status: 400 avec param: "size" signifie que la requête nécessite une correction ; cela ne signifie pas que la requête de statut elle-même a échoué. param est omis lorsqu'aucun champ spécifique n'est connu. Lorsque error_details.projection_version est 2, message est la raison finale de l'échec, généralement l'explication du service en amont, comme une limite de paramètre ou une décision de politique de contenu. Pour une tâche exécutée sur une route officielle, error_details.upstream contient également l'erreur en amont telle qu'elle a été signalée : message, ainsi que code, param et source (le nom du service en amont) lorsqu'ils sont connus. Continuez à utiliser les branchements sur code et type ; les valeurs upstream.code sont définies par le service en amont et peuvent changer.

Les erreurs qui rejettent la requête de création avant qu'une tâche ne soit acceptée utilisent le statut d'erreur HTTP normal et l'objet error structuré. Répéter la même requête de création idempotente préserve ce rejet. Une lecture de statut échouée ne modifie pas l'état terminal de la tâche.

Éviter les tâches en double

La plupart des générations en double proviennent de la répétition d'une requête de création après un délai d'attente (timeout).

Où se produit le timeoutComportement plus sûr
Avant que votre serveur ne reçoive une réponse de créationRenvoyez la même requête avec la même Idempotency-Key pour obtenir la tâche originale. Sans clé, vérifiez le request_id et ne réessayez que si aucune tâche n'a été créée
Après qu'une réponse de création a été stockéeReprenez le polling du task_id stocké
Pendant le pollingRéessayez la requête de statut avec un backoff
Après le statut terminalNe relancez pas le polling à moins que l'utilisateur n'actualise explicitement l'enregistrement

N'envoyez pas une seconde requête de création simplement parce que le navigateur a été actualisé ou qu'un polling de statut a échoué.

Enregistrements de facturation

Une tâche asynchrone peut réserver son coût estimé lorsqu'elle est acceptée. Le montant final est enregistré une fois la tâche terminée ou échouée. Les réponses de statut peuvent inclure billing_transaction_id et l'en-tête X-Billing-Transaction-ID.

Gardez ces identifiants ensemble :

  • request_id provenant de la requête de création.
  • task_id / id provenant 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} peut annuler les tâches vidéo Seedance prises en charge tant qu'elles sont encore en file d'attente, y compris seedance-2.0 et seedance-2.0-fast.

Les tâches non prises en charge renvoient 400 unsupported_task_cancel. Une tâche déjà en cours ou terminée renvoie 409 task_not_cancellable. L'annulation est une requête, pas une garantie que le travail déjà en cours s'arrêtera. Une annulation réussie renvoie 200 avec status: "failed", cancelled: true et cancellation_status: "cancelled". Une tâche annulée n'est pas facturée.

Dépannage

SymptômeCause probableÀ vérifier
404 async_task_not_foundL'ID de tâche est inconnu, appartient à un autre espace de travail, ou la tâche terminée a dépassé sa fenêtre de statutVérifiez le task_id enregistré et l'espace de travail de la clé API
403 task_not_ownedLa propriété de la tâche ne peut pas être confirmée pour l'espace de travail actuelConfirmez l'espace de travail ou l'organisation associé à la clé API
503 async_task_owner_unavailableLa propriété de la tâche n'a pas pu être vérifiée pour le moment. retryable est trueRéessayez la requête de statut avec un backoff
La tâche ne semble jamais se terminerLe client continue d'interroger la mauvaise URL ou s'est arrêté avant le statut terminalEffectuez un polling sur GET /v1/tasks/{id} avec l'ID de tâche enregistré et inspectez le dernier statut
URL multimédia finale manquanteLa tâche n'est pas terminée, ou elle s'est terminée sans fichier utilisableContinuez le polling jusqu'à ce qu'elle soit terminée, puis traitez un résultat manquant comme un échec
L'utilisateur voit des doublonsLe chemin de réessai a créé une nouvelle tâche après un timeout ou une actualisationDédupliquez par votre propre ID de travail et le task_id stocké
Erreur de facturationLa facturation finale n'est pas encore enregistrée, ou les mauvais ID sont comparésComparez request_id, task_id et billing_transaction_id

Éléments à envoyer au support

Incluez request_id, task_id, billing_transaction_id lorsqu'il est présent, le endpoint, le modèle, l'heure et les noms des champs que vous avez envoyés. N'envoyez jamais de clés API, de médias privés, d'URLs signées ou de prompts complets, sauf si le support demande spécifiquement un exemple expurgé.

Référence API

SujetRéférence
Obtenir le statut de la tâcheObtenir le statut de la tâche
Annuler une tâcheAnnuler une tâche
Génération d'imageGénération d'image
Génération de vidéoGénération de vidéo
Génération de musiqueGénération de musique
Génération 3DGénération 3D
Facturation et tarifsFacturation et tarifs

Arrêtez le polling des tâches terminales, et arrêtez-vous sur 401, 403, 404 ou une erreur non réessayable. Pour recevoir les résultats des tâches sans polling, configurez l' API de gestion des Webhooks avec un jeton de gestion mt-….

Les réponses des tâches portent également les en-têtes X-Task-ID, X-Task-Type et X-Billing-Transaction-ID, que vous pouvez consigner à côté de l'ID de tâche.

Sur cette page