TokenLab

Video & Materials

Get Video Status

Get a video task's status and result

GET
/v1/tasks/{id}

GET /v1/videos/generations/{id} is a compatibility endpoint. It remains supported for existing integrations and returns the result in the same format as GET /v1/tasks/{id}. New integrations poll GET /v1/tasks/{id}; see Get Task Status.

Path Parameters

idstringpathrequired

The task ID returned by the create video request. id and task_id identify the same task.

A status read returns HTTP 200 even when the task failed; check status. An expired or unavailable task returns 404 async_task_not_found. A task that does not belong to your workspace returns 403 task_not_owned. 503 async_task_owner_unavailable is temporary: retry the request.

Response

Fields describing results, errors, timestamps, and the model are returned when available for the task.

idstring

Task ID.

task_idstring

Same task ID as id.

poll_urlstring

Status URL for this task. Poll GET /v1/tasks/{id} with id.

billing_transaction_idstring

Billing transaction ID after settlement. It is separate from the task ID.

statusstring

Task status: pending, processing, completed, failed.

progressinteger

Optional progress from 0 to 100. Returned only when a real progress value is available; use status to determine completion.

video_urlstring

URL of the generated video (when completed). It is a TokenLab media-result URL that stays valid for 30 days; see Download the result. Failed and unfinished tasks return no video URL.

last_frame_urlstring

URL of the last generated frame, when you asked for it with return_last_frame and the model supports it.

videoobject

Single video result with url, duration, width, and height when available.

videosarray

Multiple video results when the task returns more than one output.

errorstring | object

Why the task failed (only when status is failed): a string, or an object with message and, when known, type, code, param, and retryable. A failed task can also carry error_details; see Async jobs and polling.

media_retentionobject

Saving status of the video: days and items, each with url, kind, status, and expires_at. It can be absent when the status is not known in time; the URL still works.

createdinteger

Creation timestamp.

updatedinteger

Last update timestamp.

modelstring

Model used for the task.

Request

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

Response

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

Download the Result

video_url looks like https://api.tokenlab.sh/v1/media-results/{id}.mp4?token=…. The token in the URL is the credential, so no Authorization header is needed. Share the URL only with people who may view the video. The URL redirects to the file, so follow redirects when you download (curl -L).

  • It stays valid for 30 days from when the result is first recorded. Download the file if you need it longer; see Data retention.
  • 404 media_not_found: the token or file extension does not match the result. Use the exact URL you received.
  • 410 media_expired: the 30-day period has ended.
  • 502 or 503 media_unavailable: the result is still being recorded, or TokenLab is busy. Retry after the Retry-After delay.
  • Add metadata=true to the URL to read the saving status instead of the file.

Some results are delivered as https://api.tokenlab.sh/v1/videos/generations/{id}/content. That URL needs the same Authorization: Bearer header you use for polling, and only the workspace that owns the task can open it.

Check Interval

  • Check every 5–10 seconds.
  • Increase the interval for long-running tasks.
  • Set a maximum wait time for your application.
  • Stop when the status is failed and show the returned error.
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")

Authorization

BearerAuth
AuthorizationBearer <token>

API Key authentication. Create or manage API keys in Dashboard > API > API Keys.

In: header

Path Parameters

id*string

The async task ID returned by id / task_id, or embedded in poll_url

Response

application/json

application/json

application/json

application/json

application/json

application/json

application/json