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 PubliqueCopy Anchor Link

Les réponses de création peuvent inclure :

/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éCopy Anchor Link

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.

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

Exemple de PollingCopy Anchor Link

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 ClientCopy Anchor Link

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

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èglementCopy Anchor Link

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.

AnnulationCopy Anchor Link

DELETE /v1/tasks/{id} est intentionnellement limité. Lorsque la tâche sélectionnée prend en charge l’annulation, il s’applique aux tâches vidéo Seedance en file d’attente comme 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épannageCopy Anchor Link

Paquet de SupportCopy Anchor Link

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 APICopy Anchor Link