Images
Get Image Status
Get the status and result of an async image generation task
Path Parameters
The task ID returned from the initial image generation request.
If the create response included poll_url, prefer calling that exact URL for polling. Some image tasks may surface a poll_url under /v1/tasks/{id} instead of the image-specific status path.
You can also poll public image task IDs such as ldtask_... at /v1/images/{id}. This compatibility alias 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.
Canonical async task identifier.
Preferred polling URL when the create response supplies one.
Unix timestamp of creation.
The task identifier.
Task status: pending, processing, completed, or failed.
Array of generated images (populated when status is completed).
Each object contains:
url(string): URL of the generated imagerevised_prompt(string): Optional prompt revision, when the selected model returns one
Error message (only present when status is failed).
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 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