TokenLab

Async Jobs

Get Task Status

Retrieve the status and result of any async task: images, video, music, 3D, Worlds, and async audio transcription

GET
/v1/tasks/{id}

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

idstringpathrequired

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.

idstring

Canonical async task identifier.

task_idstring

Async task identifier alias.

poll_urlstring

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

billing_transaction_idstring

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.

statusstring

Task status: pending, processing, completed, failed, or timeout. Stop polling at completed, failed, or timeout. Cancelled tasks are represented as failed with cancelled: true.

cancelledboolean

true when a queued async task was cancelled before execution.

cancellation_statusstring

Cancellation marker. Present as cancelled when cancellation succeeds.

dataarray

For completed image tasks, generated image results are returned here. Image tasks return URLs in data[].url.

progressnumber

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

video_urlstring

Result asset URL when the task completes and produces a video.

videoobject

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

videosarray

Multiple video payloads when more than one output is available.

errorstring | object

Why the task failed: a string, or an object with message and, when known, type, code, param, and retryable.

error_detailsobject

Failure details when the task failed: status, message, type, code, retryable, and param when a request field is at fault.

media_retentionobject

Saving status of the result links: days and items[] with url, kind, status, and expires_at. It can be absent; the links still work.

createdinteger

Creation timestamp when available.

updatedinteger

Last update timestamp when available.

modelstring

Model used by the task when available.

Response Headers

Successful status responses include these headers:

HeaderDescription
X-Task-IDPublic task ID
X-Task-TypeTask family, such as image, video, music, 3d, or audio
Cache-Controlno-store. Do not cache status responses
X-Billing-Transaction-IDBilling transaction ID, when one is recorded
X-Task-CostSettled task cost, when the task has settled

Error Behavior

HTTPCodeMeaning
400missing_task_id, invalid_task_idThe task ID is missing or not a valid task ID
403task_not_ownedThe task does not belong to the workspace of this API key. Stop polling it
404async_task_not_foundThe task has expired or is not available
503async_task_owner_unavailableThe 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"
  }
}

Examples

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
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