TokenLab

Images

Get Image Status

Get the status and result of an async image generation task

GET
/v1/tasks/{id}

The image-specific paths /v1/images/generations/{id} and /v1/images/{id} are compatibility endpoints. They remain supported for existing integrations. New integrations poll GET /v1/tasks/{id}; see Get Task Status.

Path Parameters

idstringpathrequired

The task ID returned from the initial image generation request.

Use the id or task_id from the create response.

The /v1/images/{id} compatibility alias accepts public image task IDs such as ldtask_.... It uses the same authorization, ownership checks, billing headers, terminal snapshots, and response shape as /v1/images/generations/{id}.

An expired or unavailable public task can return 404 async_task_not_found. If task ownership cannot be established for the current API key, the response is 403 task_not_owned.

Response

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

idstring

Canonical async task identifier.

poll_urlstring

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

createdinteger

Unix timestamp of creation.

task_idstring

The task identifier.

statusstring

Task status: pending, processing, completed, or failed.

dataarray

Array of generated images (populated when status is completed).

Each object contains:

  • url (string): TokenLab media-result URL of the generated image, valid for 30 days
  • revised_prompt (string): Optional prompt revision, when the selected model returns one
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.

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 image links: days and items[] with url, kind, status, and expires_at. It can be absent; the links still work. See Data retention.

usageobject

Token counts for token-priced models such as gpt-image-2, when available.

Request

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

Response

{
  "created": 1706000000,
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "data": []
}

Check Interval

Check every 3–5 seconds while the status is pending or processing, and stop at completed or failed.

import requests
import time

def poll_image_task(task_id, api_key, max_wait=300, interval=3):
    """Poll for image generation result with timeout."""
    url = f"https://api.tokenlab.sh/v1/tasks/{task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    start_time = time.time()
    while time.time() - start_time < max_wait:
        response = requests.get(url, headers=headers, timeout=30)
        response.raise_for_status()
        data = response.json()

        if data["status"] == "completed":
            return data["data"][0]["url"]
        elif data["status"] == "failed":
            raise Exception(data.get("error", "Generation failed"))

        time.sleep(interval)

    raise TimeoutError(f"Task {task_id} did not complete within {max_wait}s")

# Usage
image_url = poll_image_task("ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "sk-your-api-key")
print(f"Generated image: {image_url}")

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