Trabajos asíncronos

Obtener estado de la tarea

Recupere el estado y el resultado de cualquier tarea asíncrona: imágenes, video, música, 3D, Worlds y transcripción de audio asíncrona

GET
/v1/tasks/{id}

Descripción general

Utilice GET /v1/tasks/{id} para verificar cualquier tarea asíncrona. Es compatible con tareas de imagen, video, música, 3D, Worlds y transcripción de audio asíncrona. Pase el id o task_id obtenido de la respuesta de creación.

Los campos de resultado de World, como world_id y world_marble_url, están documentados en Obtener estado de World. Para una tarea de World, X-Task-Type es 3d.

Para la mayoría de las tareas, la poll_url en la respuesta de creación es esta misma ruta. Una respuesta de creación de Worlds devuelve una poll_url bajo /v1/worlds/generations/{id}; consulte /v1/tasks/{id} con el id de la tarea también para Worlds.

Las rutas de estado por modalidad, como /v1/images/{id}, /v1/videos/generations/{id}, /v1/music/generations/{id} y /v1/3d/generations/{id}, son endpoints de compatibilidad. Se mantienen admitidos para integraciones existentes.

Una lectura de estado devuelve HTTP 200 para una tarea que falló. Lea status, no el código HTTP, para ver el resultado. Los campos de resultado dependen del tipo de tarea; consulte Obtener estado de imagen, Obtener estado de video, Obtener estado de música y Obtener estado de 3D. Los enlaces de resultados son URLs de TokenLab de resultados multimedia que permanecen válidas durante 30 días; consulte Retención de datos.

Parámetros de ruta

idstringpathobligatorio

El id o task_id devuelto por la solicitud de creación.

Respuesta

Los campos que describen resultados, errores, marcas de tiempo y el modelo se devuelven cuando están disponibles para la tarea.

idstring

Identificador canónico de la tarea asíncrona.

task_idstring

Alias del identificador de la tarea asíncrona.

poll_urlstring

URL de estado para esta tarea. Consulte GET /v1/tasks/{id} con el id.

billing_transaction_idstring

ID de transacción de facturación, cuando se registra una para la tarea. El encabezado X-Billing-Transaction-ID lleva el mismo valor. Es un identificador de facturación, no un identificador de tarea.

statusstring

Estado de la tarea: pending, processing, completed, failed o timeout. Deje de consultar cuando el estado sea completed, failed o timeout. Las tareas canceladas se representan como failed con cancelled: true.

cancelledboolean

true cuando una tarea asíncrona en cola fue cancelada antes de su ejecución.

cancellation_statusstring

Marcador de cancelación. Presente como cancelled cuando la cancelación tiene éxito.

dataarray

Para tareas de imagen completadas, los resultados de las imágenes generadas se devuelven aquí. Las tareas de imagen devuelven URLs en data[].url.

progressnumber

Valor de progreso opcional. Se devuelve solo cuando hay un valor de progreso real disponible; utilice status para determinar la finalización.

video_urlstring

URL del activo resultante cuando la tarea se completa y produce un video.

videoobject

Carga útil de video único con url, duration, width y height cuando están disponibles.

videosarray

Cargas útiles de video múltiples cuando hay más de una salida disponible.

errorstring | object

Razón por la que falló la tarea: una cadena o un objeto con message y, cuando se conoce, type, code, param y retryable.

error_detailsobject

Detalles de falla cuando la tarea falló: status, message, type, code, retryable y param cuando un campo de solicitud es el causante.

media_retentionobject

Estado de guardado de los enlaces de resultados: days y items[] con url, kind, status y expires_at. Puede estar ausente; los enlaces siguen funcionando.

createdinteger

Marca de tiempo de creación cuando está disponible.

updatedinteger

Marca de tiempo de la última actualización cuando está disponible.

modelstring

Modelo utilizado por la tarea cuando está disponible.

Encabezados de respuesta

Las respuestas de estado exitosas incluyen estos encabezados:

EncabezadoDescripción
X-Task-IDID público de la tarea
X-Task-TypeFamilia de la tarea, como image, video, music, 3d o audio
Cache-Controlno-store. No almacene en caché las respuestas de estado
X-Billing-Transaction-IDID de transacción de facturación, cuando se registra una
X-Task-CostCosto liquidado de la tarea, cuando la tarea se ha liquidado

Comportamiento ante errores

HTTPCódigoSignificado
400missing_task_id, invalid_task_idEl ID de la tarea falta o no es un ID de tarea válido
403task_not_ownedLa tarea no pertenece al espacio de trabajo de esta API key. Deje de consultarla
404async_task_not_foundLa tarea ha expirado o no está disponible
503async_task_owner_unavailableLa tarea no se puede leer en este momento. Reintente
{
  "error": {
    "message": "Task not found or no longer available.",
    "type": "invalid_request_error",
    "code": "async_task_not_found"
  }
}

Ejemplos

Solicitud

curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"
{  "id": "string",  "status": "pending",  "progress": 0,  "created": 0,  "updated": 0,  "model": "string",  "video": {    "url": "string",    "duration": 0,    "width": 0,    "height": 0  },  "error": "string",  "error_details": {    "projection_version": 0,    "status": 400,    "message": "string",    "type": "string",    "code": "string",    "param": "string",    "retryable": true,    "upstream": {      "source": "string",      "code": "string",      "message": "string",      "param": "string"    }  },  "task_id": "string",  "poll_url": "string",  "cancelled": true,  "cancellation_status": "cancelled",  "billing_transaction_id": "string",  "video_url": "string",  "last_frame_url": "string",  "videos": [    {}  ],  "data": [    {}  ],  "audio_url": "string",  "title": "string",  "lyrics": "string",  "model_url": "string",  "glb_url": "string",  "fbx_url": "string",  "media_retention": {    "days": 0,    "items": [      {        "url": "http://example.com",        "kind": "image",        "content_type": "string",        "status": "saving",        "expires_at": "2019-08-24T14:15:22Z"      }    ]  }}

Autorización

BearerAuth
AuthorizationBearer <token>

Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.

Ubicación: header

Parámetros de ruta

id*string

El ID de tarea asíncrona devuelto por id / task_id, o incrustado en poll_url

Respuesta

application/json

application/json

application/json

application/json

application/json

application/json

application/json