图像

获取图像状态

获取异步图像生成任务的状态和结果

GET
/v1/tasks/{id}

图片专用路径 /v1/images/generations/{id} 和 /v1/images/{id} 是兼容端点,继续保留,供现有集成使用。新集成请调用 GET /v1/tasks/{id},详见获取任务状态。

路径参数

idstringpath必填

初始图像生成请求返回的任务 ID。

使用创建响应中的 id 或 task_id。

/v1/images/{id} 兼容地址接受 ldtask_... 图片任务 ID,与 /v1/images/generations/{id} 返回相同格式。

已过期或不可用的公开任务可能返回 404 async_task_not_found。无法确认当前 API 密钥对任务的归属权限时,返回 403 task_not_owned。

响应

结果、错误、时间戳和模型字段仅在任务提供时返回。

idstring

TokenLab 任务 ID。

poll_urlstring

任务的状态地址(如有)。用 id 调用 GET /v1/tasks/{id} 查询。

createdinteger

创建时的 Unix 时间戳。

task_idstring

任务标识符。

statusstring

任务状态:pending、processing、completed 或 failed。

dataarray

生成的图像数组(当 status 为 completed 时填充)。

每个对象包含:

  • url (string): 生成图像的 TokenLab 媒体结果 URL,有效期 30 天
  • revised_prompt (string): 所选模型返回的可选提示词改写结果
errorstring | object

任务失败原因(仅在 status 为 failed 时存在):字符串,或包含 message 以及(已知时)type、code、param、retryable 的对象。

error_detailsobject

任务失败时的失败详情:status、message、type、code、retryable,以及请求字段有误时的 param。

media_retentionobject

图片链接的保存状态:days 和 items[](含 url、kind、status、expires_at)。该字段可能不存在,链接仍可使用。见数据保留。

usageobject

按 token 计价的模型(如 gpt-image-2)在可用时返回的 token 数量。

请求

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

响应

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

查询间隔

状态为 pending 或 processing 时,每 3–5 秒查询一次;变为 completed 或 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}")

授权

BearerAuth
AuthorizationBearer <token>

API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。

位置: header

路径参数

id*string

由 id / task_id 返回或嵌入在 poll_url 中的异步任务 ID

响应

application/json

application/json

application/json

application/json

application/json

application/json

application/json