Guías principales
Trabajos Asíncronos y Polling
Crea trabajos de medios asíncronos, consulta el estado de las tareas públicas de TokenLab y reconcilia los resultados finales sin IDs específicos del proveedor.
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
modelexplí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-10spara tareas de medios de larga duración. - Detente solo cuando la tarea esté
completedofailed. - 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_idde la solicitud de creación.task_id/idde la tarea.billing_transaction_idcuando esté presente.- Tu propio ID de usuario, ID de proyecto o ID de trabajo.
Cancelación
DELETE /v1/tasks/{id} es intencionalmente limitado. Cuando la tarea seleccionada admite cancelación, se aplica a tareas de video Seedance en cola 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 |
|---|---|---|
404 async_task_not_found | La tarea ha caducado o ya no está disponible | Comprueba los valores guardados de task_id y poll_url |
403 task_not_owned | No se puede confirmar que la tarea pertenezca al espacio de trabajo actual | Comprueba el espacio de trabajo o la organización asociados a la clave API |
| 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 | Obtener estado de la tarea |
| Cancelar Tarea | Cancelar tarea |
| Generación de Imágenes | Generación de Imágenes |
| Generación de Video | Generación de Video |
| Generación de Música | Generación de Música |
| Generación 3D | Generación 3D |
| Facturación y Precios | Facturación y Precios |