Guide TokenLab sur l'annulation des tâches Seedance et la facturation des tâches en file d'attente

Les tâches de génération vidéo sont asynchrones. Lorsque vous soumettez une requête de génération vidéo via POST /v1/videos/generations, TokenLab renvoie un identifiant de tâche et met le travail en file d'attente. Si une requête est soumise par erreur, dupliquée lors d'une nouvelle tentative réseau ou abandonnée par un utilisateur final, l'annulation de la tâche pendant qu'elle est encore en file d'attente évite des coûts de calcul et de génération inutiles.

Ce guide explique comment appeler le point de terminaison d'annulation de tâche, gérer les codes de réponse de l'API et gérer les réservations de facturation ainsi que les transitions de polling.

Fonctionnement de l'annulation de tâches

L'annulation de tâches cible les travaux asynchrones qui sont encore en file d'attente dans un état pending. Dès qu'un worker de modèle commence à générer des images (faisant passer la tâche à l'état processing) ou que la tâche atteint un état terminal (completed ou failed), l'annulation ne peut plus avoir lieu.

TokenLab prend en charge l'annulation sur les modèles vidéo Seedance en file d'attente, notamment seedance-2.0, seedance-2.0-fast et seedance-2.5. Pour les intégrations utilisant le point de terminaison de compatibilité Volcengine, consultez la référence d'annulation de tâche compatible Volc.

États du cycle de vie des tâches

• pending : la tâche est en file d'attente et attend un worker disponible. L'annulation est prise en charge durant cette fenêtre.
• processing : l'exécution du modèle a commencé. Les demandes d'annulation seront rejetées.
• completed : la génération de la vidéo s'est terminée avec succès. Le résultat est prêt.
• failed : la tâche a rencontré une erreur ou a été annulée avant son exécution.

Sémantique de facturation et de réservation

Selon le guide de facturation et de tarification de TokenLab, la facturation des travaux multimédias asynchrones suit un modèle en deux phases : réservation et règlement :

1. Préautorisation / Réservation : lorsqu'une tâche vidéo asynchrone est acceptée, TokenLab peut retenir ou réserver un montant estimé en fonction du modèle et des paramètres sélectionnés.
2. Règlement : le montant final n'est réglé que lorsque la tâche atteint l'état completed. Les tâches terminées avec succès comportent un billing_transaction_id représentant l'écriture finale du grand livre.
3. Annulation et échec : les tâches qui se terminent par un état failed — y compris celles annulées alors qu'elles étaient en file d'attente — ne sont pas facturées. Toute réservation inutilisée ou retenue temporaire est recréditée sur le solde de votre espace de travail.

Puisqu'une tâche annulée dans la file d'attente ne termine jamais sa génération, elle ne génère aucun règlement de facturation final.

Annuler une tâche en file d'attente via l'API

Pour annuler une tâche, envoyez une requête DELETE à /v1/tasks/{id} avec l'identifiant de tâche retourné lors de sa création. Pour obtenir les détails complets du schéma, consultez la référence de l'API Cancel Task.

Exemple de requête

curl -X DELETE "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

Réponse en cas de succès (HTTP 200)

Lorsqu'une tâche est annulée avec succès avant le début de l'exécution, l'API répond avec un code HTTP 200. Le statut de la tâche passe directement à failed, avec la mention cancelled: true :

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "failed",
  "cancelled": true,
  "cancellation_status": "cancelled",
  "error": "Task cancelled before execution"
}

Codes d'erreur et gestion des rejets

Ne partez pas du principe qu'un appel DELETE réussit toujours. Votre application doit gérer les statuts d'erreur HTTP spécifiques :

Statut HTTP	Code d'erreur	Signification	Action recommandée
400	unsupported_task_cancel	Le modèle ou le type de tâche ne prend pas en charge l'annulation.	Laissez la tâche se terminer normalement ou vérifiez la compatibilité du modèle.
403	task_not_owned	La clé d'API n'est pas propriétaire de la tâche.	Vérifiez les identifiants de l'espace de travail et la portée de la clé d'API.
404	async_task_not_found	L'identifiant de la tâche n'existe pas ou a expiré.	Vérifiez l'identifiant de tâche enregistré dans votre base de données locale de file d'attente.
409	task_not_cancellable	La tâche a déjà commencé son exécution (processing) ou se trouve dans un état terminal (completed/failed).	Considérez que la génération est déjà en cours ; ne relancez pas l'appel de suppression en boucle.

Polling des tâches annulées

Lors de l'interrogation d'une tâche via GET /v1/tasks/{id} ou via le poll_url retourné (comme documenté dans le guide sur les tâches asynchrones et le polling), gardez à l'esprit les comportements suivants :

1. HTTP 200 sur les tâches terminales : la lecture du statut d'une tâche échouée ou annulée renvoie un code HTTP 200. Inspectez les champs status et cancelled du corps JSON plutôt que de vous fier aux codes de réponse HTTP.
2. Identification du statut : une tâche annulée affiche "status": "failed", "cancelled": true et "cancellation_status": "cancelled".
3. Absence d'identifiants de règlement : les tâches annulées ne contiendront pas de billing_transaction_id étant donné qu'aucun règlement de facturation n'a eu lieu.

import time
import requests

def cancel_and_verify(task_id: str, api_key: str):
    url = f"https://api.tokenlab.sh/v1/tasks/{task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    # Attempt cancellation
    cancel_res = requests.delete(url, headers=headers)
    if cancel_res.status_code == 200:
        data = cancel_res.json()
        if data.get("cancelled"):
            print(f"Task {task_id} successfully cancelled.")
            return True
    elif cancel_res.status_code == 409:
        print(f"Task {task_id} already in progress or terminal; cannot cancel.")
    else:
        print(f"Cancellation rejected with HTTP {cancel_res.status_code}: {cancel_res.text}")

    # Poll task to determine terminal state
    poll_res = requests.get(url, headers=headers)
    if poll_res.ok:
        status_data = poll_res.json()
        print(f"Current status: {status_data.get('status')}, cancelled: {status_data.get('cancelled', False)}")
    return False

Liste de contrôle d'intégration pour les files d'attente en production

Lors de l'intégration des flux de travail vidéo Seedance dans des architectures de workers, suivez ces bonnes pratiques :

• Persister immédiatement les identifiants : enregistrez à la fois id (ou task_id) et poll_url à partir de la réponse de POST /v1/videos/generations avant de distribuer les tâches en aval.
• Dédupliquer lors de la soumission : prévenez la création accidentelle de tâches en dédupliquant les doubles-clics côté client et les nouvelles tentatives réseau en amont avant de créer les tâches.
• Traiter l'erreur 409 comme non fatale : si une requête d'annulation renvoie 409 task_not_cancellable, traitez-la comme une indication que le traitement a commencé. Attendez le résultat et ignorez la sortie si elle n'est plus nécessaire.
• Analyser le marqueur d'annulation : dans votre boucle de polling, vérifiez à la fois status == "failed" et cancelled is True pour distinguer les annulations initiées par l'utilisateur des erreurs d'infrastructure.
• Rapprocher la facturation à l'aide des identifiants de transaction : stockez billing_transaction_id uniquement lorsqu'il est présent sur les tâches terminées (completed). Ne vous attendez pas à trouver des identifiants de transaction sur les tâches annulées ou ayant échoué.

Pour d'autres modèles d'intégration, consultez le guide de génération vidéo et la référence de l'API Get Video Status.