圖像
取得圖片狀態
取得非同步圖片生成任務的狀態與結果
圖片專用路徑 /v1/images/generations/{id} 與 /v1/images/{id} 為相容性端點。現有的整合仍可繼續使用。新的整合請輪詢 GET /v1/tasks/{id};請參閱 取得任務狀態。
路徑參數 (Path Parameters)
初始圖片生成請求所回傳的任務 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)
當任務有相關結果、錯誤、時間戳記與模型資訊時,將會回傳這些欄位。
標準的非同步任務識別碼。
此任務的狀態 URL。請使用 id 輪詢 GET /v1/tasks/{id}。
建立任務的 Unix 時間戳記。
任務識別碼。
任務狀態:pending、processing、completed 或 failed。
生成的圖片陣列(當 status 為 completed 時會填入資料)。
每個物件包含:
url(string):TokenLab 媒體結果 URL,生成的圖片連結,有效期為 30 天revised_prompt(string):選用的提示詞修正,當所選模型回傳修正內容時提供
任務失敗的原因(僅在 status 為 failed 時提供):字串,或包含 message 的物件,若已知則包含 type、code、param 與 retryable。
任務失敗時的詳細資訊:status、message、type、code、retryable,以及當請求欄位出錯時的 param。
圖片連結的儲存狀態:包含 days 與 items[](內含 url、kind、status 與 expires_at)。此欄位可能不存在;連結仍可正常運作。請參閱 資料保留。
若適用,為 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 API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。
位置: header
路徑參數
由 id / task_id 回傳,或嵌入於 poll_url 中的非同步任務 ID
回應
application/json
application/json
application/json
application/json
application/json
application/json
application/json