Trabajos Asíncronos y Polling

Muchos endpoints de medios son asíncronos. Una solicitud de creación inicia el trabajo y devuelve una identidad de tarea pública de TokenLab; tu aplicación consulta hasta que esa tarea alcanza un estado terminal. No construyas flujos de trabajo de clientes alrededor de URLs de tareas ascendentes, IDs de enrutamiento o comportamiento de callbacks del proveedor.

Contrato de Tarea Pública

Las respuestas de creación pueden incluir:

Campo	Significado	Qué hacer
`id`	ID de tarea pública de TokenLab	Almacénalo con tu propio registro de trabajo
`task_id`	Alias de compatibilidad para la misma identidad de tarea pública	Trátalo como equivalente a `id`
`status`	Estado actual de la tarea pública	Comienza a consultar cuando no esté en estado terminal
`poll_url`	URL de estado preferida	Utiliza esto primero cuando esté presente
`model`	Modelo solicitado o resuelto por el endpoint	Almacénalo para soporte y reconciliación de facturación

/v1/tasks/{id} es el endpoint de estado fijo canónico para trabajos de medios asíncronos públicos. Pueden existir rutas de estado específicas de medios para compatibilidad, pero las nuevas integraciones deberían preferir poll_url o /v1/tasks/{id}.

Flujo Recomendado

Valida la solicitud del usuario y envía la llamada de creación con un model explícito.
Persiste id / task_id, poll_url, endpoint, modelo, ID de usuario y tu propio ID de trabajo antes de devolver el control a la UI.
Consulta cada 5-10s para tareas de medios de larga duración.
Detente solo cuando la tarea esté completed o failed.
En completed, lee los campos de resultado específicos de medios y almacena las URLs finales o metadatos.
En failed, almacena el error público y ofrece reintentar solo como un nuevo trabajo visible para el usuario.

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

Ejemplo de Polling

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

Los estados públicos esperados son pending, processing, completed y failed. Las tareas canceladas se representan como failed con cancelled: true y cancellation_status: "cancelled" para que el manejo de estados más antiguos siga funcionando.

Reglas de Reintento del Cliente

Los tiempos de espera de red son la fuente más común de trabajos duplicados. Usa esta regla:

Donde ocurre el tiempo de espera	Comportamiento más seguro
Antes de que tu servidor reciba una respuesta de creación	Verifica los registros del servidor para `request_id`; reintenta solo si no se creó ninguna tarea
Después de que se almacenó una respuesta de creación	Reanuda el polling del `task_id` almacenado
Durante el polling	Reintenta la solicitud de estado con retroceso
Después del estado terminal	No consultes de nuevo a menos que el usuario actualice explícitamente el registro

No envíes una segunda solicitud de creación solo porque el navegador se refrescó o una consulta de estado falló.

Facturación y Liquidación

Los trabajos asíncronos pueden reservar una cantidad estimada cuando se acepta la solicitud de creación. La liquidación final ocurre después del estado terminal. Cuando esté disponible, las respuestas de estado de tarea pueden exponer billing_transaction_id y el encabezado X-Billing-Transaction-ID. Para la reconciliación, une estos identificadores en tus registros:

request_id de la solicitud de creación.
task_id / id de la tarea.
billing_transaction_id cuando esté presente.
Tu propio ID de usuario, ID de proyecto o ID de trabajo.

Cancelación

DELETE /v1/tasks/{id} es intencionalmente estrecho. Actualmente soporta tareas de video en cola de Volcengine Seedance como seedance-1.5-pro, seedance-2.0 y seedance-2.0-fast. Las tareas no soportadas devuelven 400 unsupported_task_cancel. Las tareas que ya están en ejecución o en estado terminal devuelven 409 task_not_cancellable. Construye la UI de cancelación como “solicitar cancelación” en lugar de un botón de parada garantizado.

Solución de Problemas

Síntoma	Causa probable	Qué verificar
`async_task_not_found`	La tarea es desconocida, ha expirado, es inaccesible para esta clave API, o no es una tarea pública asíncrona	Confirma la propiedad de la clave API y el `task_id` público almacenado
La tarea nunca parece terminar	El cliente sigue consultando la URL incorrecta o se detuvo antes del estado terminal	Usa `poll_url` o `/v1/tasks/{id}` e inspecciona el estado más reciente
URL final de medios faltante	La tarea no está completada, o el trabajo ascendente se completó sin salida utilizable	Sigue consultando hasta el estado terminal, luego maneja la salida faltante como fallida
El usuario ve duplicados	La ruta de reintento creó una nueva tarea después de un tiempo de espera o refresco	Deduplica por tu propio ID de trabajo y `task_id` almacenado
Desajuste de facturación	La liquidación es asíncrona o el cliente está comparando IDs de proveedor	Compara `request_id`, `task_id` y `billing_transaction_id`

Paquete de Soporte

Al contactar con soporte, incluye request_id, task_id, billing_transaction_id cuando esté presente, endpoint, modelo, marca de tiempo y una forma de solicitud sanitizada. No incluyas claves API, medios privados, URLs firmadas o prompts completos a menos que el soporte pida una muestra redactada.

Referencia de API

Tema	Referencia
Obtener Estado de Tarea	Get Task Status
Cancelar Tarea	Cancel Task
Generación de Imágenes	Image Generation
Generación de Video	Video Generation
Generación de Música	Music Generation
Generación 3D	3D Generation
Facturación y Precios	Billing & Pricing

​Contrato de Tarea Pública

​Flujo Recomendado

​Ejemplo de Polling

​Reglas de Reintento del Cliente

​Facturación y Liquidación

​Cancelación

​Solución de Problemas

​Paquete de Soporte

​Referencia de API