Guías principales
Tareas asíncronas y polling
Cree tareas de medios y espere el resultado final
Muchos endpoints de medios devuelven una tarea en lugar de un archivo finalizado. Guarde el ID de la tarea devuelto y realice polling a GET /v1/tasks/{id} hasta que el estado sea completed o failed. Este único endpoint sirve para tareas de imagen, video, música, 3D, Worlds y transcripción de audio asíncrona.
Las instantáneas de tareas terminales asíncronas tienen un ciclo de vida separado de la ventana de captura de solicitud/respuesta de 30 días. Las URLs de archivos de imagen, video, audio, 3D y Worlds generados son URLs de resultados de medios de TokenLab que permanecen válidas durante 30 días. Las lecturas de estado de tareas finalizadas funcionan durante unos 7 días, por lo que debe guardar el resultado tan pronto como la tarea se complete. Los campos media_retention de la respuesta informan sobre el estado de guardado de cada elemento y su expires_at; estos pueden estar ausentes cuando el estado de guardado no se conoce a tiempo, y la URL sigue funcionando. Las tareas fallidas y en progreso devuelven campos de URL de medios vacíos. Consulte Retención de datos.
Campos a guardar
Las respuestas de creación pueden incluir:
| Campo | Significado | Qué hacer |
|---|---|---|
id | ID de tarea de TokenLab | Guárdelo con su propio registro de trabajo |
task_id | Otro nombre para el mismo ID de tarea | Trátelo como equivalente a id |
status | Estado actual de la tarea | Siga verificando hasta que termine o falle |
poll_url | URL de estado para la tarea | Guárdela; realice polling a /v1/tasks/{id} con el ID de la tarea |
model | Modelo utilizado para la tarea | Guárdelo con el registro de la tarea |
Un único endpoint de estado
Realice polling a GET /v1/tasks/{id} con el id o task_id de la respuesta de creación. Funciona para todos los tipos de tareas. Para la mayoría de las tareas, poll_url es esta misma ruta. Una respuesta de creación de Worlds devuelve una poll_url bajo /v1/worlds/generations/{id}; realice polling a /v1/tasks/{id} con el id de la tarea para Worlds también.
Las rutas de estado por modalidad, como /v1/videos/generations/{id}, siguen siendo compatibles para integraciones existentes. Las nuevas integraciones deben usar /v1/tasks/{id}.
Guardar la tarea y verificar su estado
Guarde el id o task_id tan pronto como la solicitud de creación tenga éxito. Almacene la poll_url, el modelo, el endpoint y su propio ID de usuario o de trabajo junto con él. Para trabajos de medios largos, verificar cada 5–10 segundos suele ser suficiente.
Deténgase cuando el estado sea completed o failed. Una tarea completada contiene el resultado de los medios; una tarea fallida contiene el error que puede mostrar o registrar. Reintentar una generación fallida crea una nueva tarea y puede generar un nuevo cargo.
{
"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 son pending, processing, completed y failed. Una tarea cancelada utiliza failed junto con cancelled: true y cancellation_status: "cancelled".
Una lectura de estado exitosa devuelve HTTP 200 incluso cuando la tarea ha fallado. Utilice el status de la tarea para decidir si la generación tuvo éxito. El campo error conserva su forma de cadena u objeto. Las tareas fallidas también pueden incluir error_details con status (el estado de error de negocio), type, code, message, param y retryable. Por ejemplo, error_details.status: 400 con param: "size" significa que la solicitud necesita corrección; no significa que la solicitud de estado en sí haya fallado. param se omite cuando no se conoce ningún campo específico. Cuando error_details.projection_version es 2, message es la razón final del fallo, generalmente la explicación del propio servicio upstream, como un límite de parámetros o una decisión de política de contenido. Para una tarea que se ejecutó en una ruta oficial, error_details.upstream también lleva el error upstream según lo informado: message, además de code, param y source (el nombre del servicio upstream) cuando se conoce. Siga ramificando según code y type; los valores de upstream.code son definidos por el servicio upstream y pueden cambiar.
Los errores que rechazan la solicitud de creación antes de que se acepte una tarea utilizan el estado de error HTTP normal y el objeto error estructurado. Repetir la misma solicitud de creación idempotente preserva ese rechazo. Una lectura de estado fallida no cambia el estado terminal de la tarea.
Evitar tareas duplicadas
La mayoría de las generaciones duplicadas provienen de reintentar una solicitud de creación después de un tiempo de espera (timeout).
| Dónde ocurre el timeout | Comportamiento más seguro |
|---|---|
| Antes de que su servidor reciba una respuesta de creación | Envíe la misma solicitud nuevamente con el mismo Idempotency-Key para obtener la tarea original. Sin una clave, verifique el request_id y reintente solo si no se creó ninguna tarea |
| Después de que se almacenó una respuesta de creación | Reanude el polling del task_id almacenado |
| Durante el polling | Reintente la solicitud de estado con backoff |
| Después del estado terminal | No realice polling nuevamente a menos que el usuario actualice explícitamente el registro |
No envíe una segunda solicitud de creación solo porque el navegador se actualizó o un polling de estado falló.
Registros de facturación
Una tarea asíncrona puede reservar su costo estimado cuando es aceptada. El monto final se registra después de que la tarea termina o falla. Las respuestas de estado pueden incluir billing_transaction_id y el encabezado X-Billing-Transaction-ID.
Mantenga estos identificadores juntos:
request_idde la solicitud de creación.task_id/idde la tarea.billing_transaction_idcuando esté presente.- Su propio ID de usuario, ID de proyecto o ID de trabajo.
Cancelación
DELETE /v1/tasks/{id} puede cancelar tareas de video Seedance compatibles mientras aún están en cola, incluyendo seedance-2.0 y seedance-2.0-fast.
Las tareas no compatibles devuelven 400 unsupported_task_cancel. Una tarea que ya se está ejecutando o ha terminado devuelve 409 task_not_cancellable. La cancelación es una solicitud, no una garantía de que el trabajo ya en progreso se detendrá. Una cancelación exitosa devuelve 200 con status: "failed", cancelled: true y cancellation_status: "cancelled". Una tarea cancelada no se cobra.
Solución de problemas
| Síntoma | Causa probable | Qué verificar |
|---|---|---|
404 async_task_not_found | El ID de la tarea es desconocido, pertenece a otro espacio de trabajo o la tarea finalizada ha superado su ventana de estado | Verifique el task_id guardado y el espacio de trabajo de la API key |
403 task_not_owned | No se puede confirmar la propiedad de la tarea para el espacio de trabajo actual | Confirme el espacio de trabajo u organización asociada con la API key |
503 async_task_owner_unavailable | No se pudo verificar la propiedad de la tarea en este momento. retryable es true | Reintente la solicitud de estado con backoff |
| La tarea nunca parece terminar | El cliente sigue haciendo polling a la URL incorrecta o se detuvo antes del estado terminal | Realice polling a GET /v1/tasks/{id} con el ID de tarea guardado e inspeccione el estado más reciente |
| Falta la URL de medios final | La tarea no está completada o terminó sin un archivo utilizable | Siga haciendo polling hasta que termine, luego trate un resultado faltante como fallido |
| El usuario ve duplicados | La ruta de reintento creó una nueva tarea después de un timeout o actualización | Desduplique por su propio ID de trabajo y el task_id almacenado |
| Discrepancia de facturación | La facturación final aún no se ha registrado o se están comparando los IDs incorrectos | Compare request_id, task_id y billing_transaction_id |
Qué enviar a soporte
Incluya request_id, task_id, billing_transaction_id cuando esté presente, endpoint, modelo, hora y los nombres de los campos que envió. Nunca envíe API keys, medios privados, URLs firmadas o prompts completos a menos que soporte solicite específicamente un ejemplo redactado.
Referencia de la API
| Tema | Referencia |
|---|---|
| Obtener estado de tarea | Obtener estado de 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 |
Deje de hacer polling a tareas terminales y deténgase en 401, 403, 404 o un error no reintentable. Para recibir resultados de tareas sin hacer polling, configure la API de gestión de Webhooks con un Management Token mt-….
Las respuestas de las tareas también llevan los encabezados X-Task-ID, X-Task-Type y X-Billing-Transaction-ID, que puede registrar junto al ID de la tarea.