Video y recursos

Obtener estado del video

Obtener el estado y el resultado de una tarea de video

GET
/v1/tasks/{id}

GET /v1/videos/generations/{id} es un endpoint de compatibilidad. Se mantiene para integraciones existentes y devuelve el resultado en el mismo formato que GET /v1/tasks/{id}. Las nuevas integraciones deben realizar el sondeo (polling) en GET /v1/tasks/{id}; consulte Obtener estado de la tarea.

Parámetros de ruta

idstringpathobligatorio

El ID de la tarea devuelto por la solicitud de creación de video. id y task_id identifican la misma tarea.

Una lectura de estado devuelve HTTP 200 incluso cuando la tarea ha fallado; verifique status. Una tarea caducada o no disponible devuelve 404 async_task_not_found. Una tarea que no pertenece a su espacio de trabajo devuelve 403 task_not_owned. 503 async_task_owner_unavailable es temporal: vuelva a intentar la solicitud.

Respuesta

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

idstring

ID de la tarea.

task_idstring

El mismo ID de tarea que id.

poll_urlstring

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

billing_transaction_idstring

ID de la transacción de facturación tras la liquidación. Es independiente del ID de la tarea.

statusstring

Estado de la tarea: pending, processing, completed, failed.

progressinteger

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

video_urlstring

URL del video generado (cuando se completa). Es una URL de resultado multimedia de TokenLab que permanece válida durante 30 días; consulte Descargar el resultado. Las tareas fallidas o inacabadas no devuelven ninguna URL de video.

last_frame_urlstring

URL del último fotograma generado, cuando lo solicitó con return_last_frame y el modelo lo admite.

videoobject

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

videosarray

Resultados de video múltiples cuando la tarea devuelve más de una salida.

errorstring | object

Motivo por el cual falló la tarea (solo cuando status es failed): una cadena o un objeto con message y, cuando se conoce, type, code, param y retryable. Una tarea fallida también puede incluir error_details; consulte Trabajos asíncronos y sondeo.

media_retentionobject

Estado de guardado del video: days y items, cada uno con url, kind, status y expires_at. Puede estar ausente cuando el estado no se conoce a tiempo; la URL sigue funcionando.

createdinteger

Marca de tiempo de creación.

updatedinteger

Marca de tiempo de la última actualización.

modelstring

Modelo utilizado para la tarea.

Solicitud

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

Respuesta

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

Descargar el resultado

video_url tiene el formato https://api.tokenlab.sh/v1/media-results/{id}.mp4?token=…. El token en la URL es la credencial, por lo que no se necesita el encabezado Authorization. Comparta la URL solo con personas que puedan ver el video. La URL redirige al archivo, así que siga las redirecciones al descargar (curl -L).

  • Permanece válida durante 30 días desde que se registra el resultado por primera vez. Descargue el archivo si lo necesita por más tiempo; consulte Retención de datos.
  • 404 media_not_found: el token o la extensión del archivo no coinciden con el resultado. Utilice la URL exacta que recibió.
  • 410 media_expired: el período de 30 días ha finalizado.
  • 502 o 503 media_unavailable: el resultado aún se está grabando o TokenLab está ocupado. Vuelva a intentarlo después del retraso indicado en Retry-After.
  • Añada metadata=true a la URL para leer el estado de guardado en lugar del archivo.

Algunos resultados se entregan como https://api.tokenlab.sh/v1/videos/generations/{id}/content. Esa URL requiere el mismo encabezado Authorization: Bearer que utiliza para el sondeo, y solo el espacio de trabajo propietario de la tarea puede abrirla.

Intervalo de comprobación

  • Compruebe cada 5–10 segundos.
  • Aumente el intervalo para tareas de larga duración.
  • Establezca un tiempo de espera máximo para su aplicación.
  • Deténgase cuando el estado sea failed y muestre el error devuelto.
import requests
import time

def wait_for_video(task_id, max_wait=600, interval=5):
    """Wait for video with timeout."""
    start = time.time()

    while time.time() - start < max_wait:
        response = requests.get(
            f"https://api.tokenlab.sh/v1/tasks/{task_id}",
            headers={"Authorization": "Bearer sk-your-api-key"}
        )
        response.raise_for_status()
        data = response.json()

        if data["status"] == "completed":
            return data["video_url"]
        elif data["status"] == "failed":
            raise Exception(data.get("error", "Video generation failed"))

        time.sleep(interval)

    raise TimeoutError("Video generation timed out")

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