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 :
| Champ | Signification | Action à effectuer |
|---|---|---|
id | ID de tâche TokenLab | Stockez-le avec votre propre enregistrement de travail |
task_id | Autre nom pour le même ID de tâche | Traitez-le comme équivalent à id |
status | Statut actuel de la tâche | Continuez à vérifier jusqu'à ce qu'elle soit terminée ou échouée |
poll_url | URL de statut de la tâche | Stockez-la ; effectuez un polling sur /v1/tasks/{id} avec l'ID de tâche |
model | Modèle utilisé pour la tâche | Stockez-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 timeout | Comportement plus sûr |
|---|---|
| Avant que votre serveur ne reçoive une réponse de création | Renvoyez 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ée | Reprenez le polling du task_id stocké |
| Pendant le polling | Réessayez la requête de statut avec un backoff |
| Après le statut terminal | Ne 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_idprovenant de la requête de création.task_id/idprovenant de la tâche.billing_transaction_idlorsqu'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ôme | Cause probable | À vérifier |
|---|---|---|
404 async_task_not_found | L'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 statut | Vérifiez le task_id enregistré et l'espace de travail de la clé API |
403 task_not_owned | La propriété de la tâche ne peut pas être confirmée pour l'espace de travail actuel | Confirmez l'espace de travail ou l'organisation associé à la clé API |
503 async_task_owner_unavailable | La propriété de la tâche n'a pas pu être vérifiée pour le moment. retryable est true | Réessayez la requête de statut avec un backoff |
| La tâche ne semble jamais se terminer | Le client continue d'interroger la mauvaise URL ou s'est arrêté avant le statut terminal | Effectuez un polling sur GET /v1/tasks/{id} avec l'ID de tâche enregistré et inspectez le dernier statut |
| URL multimédia finale manquante | La tâche n'est pas terminée, ou elle s'est terminée sans fichier utilisable | Continuez le polling jusqu'à ce qu'elle soit terminée, puis traitez un résultat manquant comme un échec |
| L'utilisateur voit des doublons | Le chemin de réessai a créé une nouvelle tâche après un timeout ou une actualisation | Dédupliquez par votre propre ID de travail et le task_id stocké |
| Erreur de facturation | La facturation finale n'est pas encore enregistrée, ou les mauvais ID sont comparés | Comparez 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
| Sujet | Référence |
|---|---|
| Obtenir le statut de la tâche | Obtenir le statut de la tâche |
| Annuler une tâche | Annuler une tâche |
| Génération d'image | Génération d'image |
| Génération de vidéo | Génération de vidéo |
| Génération de musique | Génération de musique |
| Génération 3D | Génération 3D |
| Facturation et tarifs | Facturation 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.