TokenLab

圖像

取得圖片狀態

取得非同步圖片生成任務的狀態與結果

GET
/v1/tasks/{id}

圖片專用路徑 /v1/images/generations/{id} 與 /v1/images/{id} 為相容性端點。現有的整合仍可繼續使用。新的整合請輪詢 GET /v1/tasks/{id};請參閱 取得任務狀態。

路徑參數 (Path Parameters)

idstringpath必填

初始圖片生成請求所回傳的任務 ID。

請使用建立回應中的 id 或 task_id。

/v1/images/{id} 相容性別名接受公開的圖片任務 ID,例如 ldtask_...。它使用與 /v1/images/generations/{id} 相同的授權、所有權檢查、計費標頭、終端快照與回應格式。

若公開任務已過期或無法取得,可能會回傳 404 async_task_not_found。若無法為當前的 API key 建立任務所有權,回應將為 403 task_not_owned。

回應 (Response)

當任務有相關結果、錯誤、時間戳記與模型資訊時,將會回傳這些欄位。

idstring

標準的非同步任務識別碼。

poll_urlstring

此任務的狀態 URL。請使用 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

若適用,為 gpt-image-2 等按 Token 計費的模型提供 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": []
}

檢查間隔 (Check Interval)

當狀態為 pending 或 processing 時,請每 3–5 秒檢查一次,並在狀態變為 completed 或 failed 時停止。

import requests
import time

def poll_image_task(task_id, api_key, max_wait=300, interval=3):
    """輪詢圖片生成結果並設定逾時。"""
    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")

# 使用方式
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 金鑰。

位置: header

路徑參數

id*string

由 id / task_id 回傳,或嵌入於 poll_url 中的非同步任務 ID

回應

application/json

application/json

application/json

application/json

application/json

application/json

application/json