Async Jobs
Get Task Status
Retrieve the status and result of any async task: images, video, music, 3D, Worlds, and async audio transcription
Overview
Use GET /v1/tasks/{id} to check any async task. It serves image, video, music, 3D, Worlds, and async audio transcription tasks. Pass the id or task_id from the create response.
World result fields, such as world_id and world_marble_url, are documented on Get World Status. For a World task, X-Task-Type is 3d.
For most tasks, the poll_url in the create response is this same path. A Worlds create response returns a poll_url under /v1/worlds/generations/{id}; poll /v1/tasks/{id} with the task id for Worlds too.
Per-modality status paths, such as /v1/images/{id}, /v1/videos/generations/{id}, /v1/music/generations/{id}, and /v1/3d/generations/{id}, are compatibility endpoints. They remain supported for existing integrations.
A status read returns HTTP 200 for a task that failed. Read status, not the HTTP code, to see the outcome. The result fields depend on the task type; see Get Image Status, Get Video Status, Get Music Status, and Get 3D Status. Result links are TokenLab media-result URLs that stay valid for 30 days; see Data retention.
Path Parameters
The id or task_id returned by the create request.
Response
Fields describing results, errors, timestamps, and the model are returned when available for the task.
Canonical async task identifier.
Async task identifier alias.
Status URL for this task. Poll GET /v1/tasks/{id} with id.
Billing transaction ID, when one is recorded for the task. The X-Billing-Transaction-ID header carries the same value. It is a billing identifier, not a task identifier.
Task status: pending, processing, completed, failed, or timeout. Stop polling at completed, failed, or timeout. Cancelled tasks are represented as failed with cancelled: true.
true when a queued async task was cancelled before execution.
Cancellation marker. Present as cancelled when cancellation succeeds.
For completed image tasks, generated image results are returned here. Image tasks return URLs in data[].url.
Optional progress value. Returned only when a real progress value is available; use status to determine completion.
Result asset URL when the task completes and produces a video.
Single video payload with url, duration, width, and height when available.
Multiple video payloads when more than one output is available.
Why the task failed: a string, or an object with message and, when known, type, code, param, and retryable.
Failure details when the task failed: status, message, type, code, retryable, and param when a request field is at fault.
Saving status of the result links: days and items[] with url, kind, status, and expires_at. It can be absent; the links still work.
Creation timestamp when available.
Last update timestamp when available.
Model used by the task when available.
Response Headers
Successful status responses include these headers:
| Header | Description |
|---|---|
X-Task-ID | Public task ID |
X-Task-Type | Task family, such as image, video, music, 3d, or audio |
Cache-Control | no-store. Do not cache status responses |
X-Billing-Transaction-ID | Billing transaction ID, when one is recorded |
X-Task-Cost | Settled task cost, when the task has settled |
Error Behavior
| HTTP | Code | Meaning |
|---|---|---|
400 | missing_task_id, invalid_task_id | The task ID is missing or not a valid task ID |
403 | task_not_owned | The task does not belong to the workspace of this API key. Stop polling it |
404 | async_task_not_found | The task has expired or is not available |
503 | async_task_owner_unavailable | The task cannot be read right now. Retry |
{
"error": {
"message": "Task not found or no longer available.",
"type": "invalid_request_error",
"code": "async_task_not_found"
}
}Request
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" } ] }}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