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:

CampoSignificadoQué hacer
idID de tarea de TokenLabGuárdelo con su propio registro de trabajo
task_idOtro nombre para el mismo ID de tareaTrátelo como equivalente a id
statusEstado actual de la tareaSiga verificando hasta que termine o falle
poll_urlURL de estado para la tareaGuárdela; realice polling a /v1/tasks/{id} con el ID de la tarea
modelModelo utilizado para la tareaGuá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 timeoutComportamiento más seguro
Antes de que su servidor reciba una respuesta de creaciónEnví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ónReanude el polling del task_id almacenado
Durante el pollingReintente la solicitud de estado con backoff
Después del estado terminalNo 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_id de la solicitud de creación.
  • task_id / id de la tarea.
  • billing_transaction_id cuando 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íntomaCausa probableQué verificar
404 async_task_not_foundEl ID de la tarea es desconocido, pertenece a otro espacio de trabajo o la tarea finalizada ha superado su ventana de estadoVerifique el task_id guardado y el espacio de trabajo de la API key
403 task_not_ownedNo se puede confirmar la propiedad de la tarea para el espacio de trabajo actualConfirme el espacio de trabajo u organización asociada con la API key
503 async_task_owner_unavailableNo se pudo verificar la propiedad de la tarea en este momento. retryable es trueReintente la solicitud de estado con backoff
La tarea nunca parece terminarEl cliente sigue haciendo polling a la URL incorrecta o se detuvo antes del estado terminalRealice polling a GET /v1/tasks/{id} con el ID de tarea guardado e inspeccione el estado más reciente
Falta la URL de medios finalLa tarea no está completada o terminó sin un archivo utilizableSiga haciendo polling hasta que termine, luego trate un resultado faltante como fallido
El usuario ve duplicadosLa ruta de reintento creó una nueva tarea después de un timeout o actualizaciónDesduplique por su propio ID de trabajo y el task_id almacenado
Discrepancia de facturaciónLa facturación final aún no se ha registrado o se están comparando los IDs incorrectosCompare 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

TemaReferencia
Obtener estado de tareaObtener estado de tarea
Cancelar tareaCancelar tarea
Generación de imágenesGeneración de imágenes
Generación de videoGeneración de video
Generación de músicaGeneración de música
Generación 3DGeneración 3D
Facturación y preciosFacturació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.

En esta página