Guía de cancelación de tareas Seedance y facturación de trabajos en cola en TokenLab

Las tareas de generación de video son asíncronas. Cuando envía una solicitud de generación de video a través de POST /v1/videos/generations, TokenLab devuelve un identificador de tarea y pone el trabajo en cola. Si una solicitud se envía por error, se duplica durante un reintento de red o es abandonada por un usuario final, cancelar la tarea mientras permanece en cola evita cargos innecesarios de cómputo y generación.

Esta guía explica cómo llamar al endpoint de cancelación de tareas, gestionar los códigos de respuesta de la API y administrar las reservas de facturación y las transiciones de sondeo (polling).

Cómo funciona la cancelación de tareas

La cancelación de tareas está dirigida a trabajos asíncronos que todavía están en cola en un estado pending. Una vez que un worker del modelo comienza a generar fotogramas (haciendo la transición de la tarea a processing) o la tarea alcanza un estado terminal (completed o failed), la cancelación ya no puede llevarse a cabo.

TokenLab admite la cancelación en modelos de video Seedance en cola, incluidos seedance-2.0, seedance-2.0-fast y seedance-2.5. Para integraciones que utilizan el endpoint de compatibilidad con Volcengine, consulte la referencia de cancelación de tareas compatibles con Volc.

Estados del ciclo de vida de la tarea

• pending: La tarea está en cola y esperando un worker disponible. La cancelación se admite en esta ventana.
• processing: La ejecución del modelo ha comenzado. Las solicitudes de cancelación serán rechazadas.
• completed: La generación de video finalizó con éxito. El resultado está listo.
• failed: La tarea encontró un error o fue cancelada antes de la ejecución.

Semántica de cobro y reserva

De acuerdo con la guía de facturación y precios de TokenLab, la facturación de trabajos multimedia asíncronos sigue un modelo de dos fases de reserva y liquidación:

1. Preautorización / Reserva: Cuando se acepta una tarea de video asíncrona, TokenLab puede retener o reservar un monto estimado basado en el modelo y los parámetros seleccionados.
2. Liquidación: El cargo final se liquida únicamente cuando la tarea alcanza el estado completed. Las tareas completadas adjuntan un billing_transaction_id que representa la entrada final en el libro mayor.
3. Cancelación y fallo: Las tareas que terminan en un estado failed—incluidas aquellas canceladas mientras estaban en cola—no se cobran. Cualquier reserva no utilizada o retención temporal se libera de vuelta al saldo de su espacio de trabajo.

Debido a que una tarea cancelada en la cola nunca completa la generación, no genera una liquidación de facturación completada.

Cancelar una tarea en cola a través de la API

Para cancelar una tarea, envíe una solicitud DELETE a /v1/tasks/{id} con el ID de tarea devuelto durante la creación. Para obtener detalles completos del esquema, consulte la referencia de la API para cancelar tareas.

Ejemplo de solicitud

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

Respuesta exitosa (HTTP 200)

Cuando una tarea se cancela exitosamente antes de que comience la ejecución, la API responde con HTTP 200. El estado de la tarea pasa directamente a failed, marcado con 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"
}

Códigos de error y gestión de rechazos

No asuma que una llamada DELETE siempre tiene éxito. Su aplicación debe manejar estados de error HTTP específicos:

Estado HTTP	Código de error	Significado	Acción recomendada
400	unsupported_task_cancel	El modelo o tipo de tarea no admite cancelación.	Deje que la tarea termine normalmente o revise la compatibilidad del modelo.
403	task_not_owned	La clave de API no es propietaria de la tarea.	Verifique las credenciales del espacio de trabajo y el alcance de la clave de API.
404	async_task_not_found	El ID de tarea no existe o ha expirado.	Confirme el ID de tarea almacenado en la base de datos de cola local.
409	task_not_cancellable	La tarea ya ha comenzado a procesarse (processing) o se encuentra en un estado terminal (completed/failed).	Acepte que la generación ya está en marcha; no reintente la llamada de eliminación en un bucle.

Sondeo (polling) de tareas canceladas

Al sondear una tarea a través de GET /v1/tasks/{id} o la poll_url devuelta (como se documenta en la guía de trabajos asíncronos y sondeo), tenga en cuenta los siguientes comportamientos:

1. HTTP 200 en tareas terminales: Leer el estado de una tarea fallida o cancelada devuelve HTTP 200. Inspeccione los campos status y cancelled del cuerpo JSON en lugar de depender de los códigos de respuesta HTTP.
2. Identificación del estado: Una tarea cancelada muestra "status": "failed", "cancelled": true y "cancellation_status": "cancelled".
3. Ausencia de IDs de liquidación: Las tareas canceladas no contendrán un billing_transaction_id ya que no se produjo ninguna liquidación de cobro.

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

Lista de verificación para integración de colas en producción

Al integrar flujos de trabajo de video Seedance en arquitecturas de workers, siga estas mejores prácticas:

• Persistir los IDs inmediatamente: Almacene tanto id (o task_id) como poll_url de la respuesta de POST /v1/videos/generations antes de despachar el trabajo posterior.
• Desduplicar al enviar: Evite la generación accidental de tareas desduplicando los dobles clics del lado del cliente y los reintentos de red ascendentes antes de crear las tareas.
• Manejar 409 como no fatal: Si una solicitud de cancelación devuelve 409 task_not_cancellable, trátelo como una indicación de que el procesamiento ha comenzado. Recurra a esperar el resultado y descartar la salida si ya no es necesaria.
• Analizar el marcador de cancelación: En su bucle de sondeo, verifique tanto status == "failed" como cancelled is True para distinguir las cancelaciones iniciadas por el usuario de los errores de infraestructura.
• Conciliar la facturación utilizando los ID de transacción: Almacene billing_transaction_id solo cuando esté presente en trabajos completados. No espere IDs de transacción en tareas canceladas o fallidas.

Para patrones de integración adicionales, revise la guía de generación de video y la referencia de la API para obtener el estado del video.