Video & Materials
Get Video Status
Get a video task's status and result
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
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.
Task ID.
Same task ID as id.
Status URL for this task. Poll GET /v1/tasks/{id} with id.
Billing transaction ID after settlement. It is separate from the task ID.
Task status: pending, processing, completed, failed.
Optional progress from 0 to 100. Returned only when a real progress value is available; use status to determine completion.
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.
URL of the last generated frame, when you asked for it with return_last_frame and the model supports it.
Single video result with url, duration, width, and height when available.
Multiple video results when the task returns more than one output.
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.
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.
Creation timestamp.
Last update timestamp.
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.502or503 media_unavailable: the result is still being recorded, or TokenLab is busy. Retry after theRetry-Afterdelay.- Add
metadata=trueto 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
failedand show the returnederror.
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 API Key authentication. Create or manage API keys in Dashboard > API > API Keys.
In: header
Path Parameters
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