TokenLab

視頻與素材

取得影片狀態

取得影片產生任務的狀態與結果

GET
/v1/tasks/{id}

路徑參數

idstringpath必填

從建立影片請求回傳的任務 ID。將 id 與 task_id 視為相同的非同步識別碼。

如果 create 回應回傳 poll_url,請呼叫該 URL。當它指向 /v1/tasks/{id} 時,視為固定的標準狀態端點。

已過期或不可用的公開任務可能回傳 404 async_task_not_found。無法確認目前 API 金鑰對任務的歸屬權限時,回傳 403 task_not_owned。

回應

結果、錯誤、時間戳記與模型欄位僅在任務提供時回傳。

idstring

正規的非同步任務識別符。

task_idstring

非同步任務識別符的別名。

poll_urlstring

當建立回應提供時,建議用來輪詢的 URL。

billing_transaction_idstring

當結算已完成時返回 TokenLab 帳單交易 ID。它對應 dashboard / 對帳使用的交易識別,與非同步 id / task_id 不同。

statusstring

任務狀態:pending、processing、completed、failed。

progressnumber

可選進度值。僅在任務提供真實進度時返回;請使用 status 判斷任務是否完成。

video_urlstring

產生影片的 URL(完成時)。

videoobject

單一影片資料,當可用時包含 url、duration、width 與 height。

videosarray

當生成任務回傳多個輸出時的多重影片資料。

errorstring | object

錯誤訊息(若失敗)。

createdinteger

建立時間戳記。

updatedinteger

最後更新時間戳記。

modelstring

任務使用的模型。

請求

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

回應

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "veo3.1",
  "created": 1706000000,
  "updated": 1706000000
}

輪詢最佳做法

  • 每 5 到 10 秒輪詢一次
  • 對於較長的任務實作指數退避
  • 設定最大逾時(例如:10 分鐘)
  • 優雅地處理 failed 狀態
import requests
import time

def wait_for_video(task_id, max_wait=600, interval=5):
    """Wait for video with timeout."""
    start = time.time()

    while time.time() - start < max_wait:
        response = requests.get(
            f"https://api.tokenlab.sh/v1/tasks/{task_id}",
            headers={"Authorization": "Bearer sk-your-api-key"}
        )
        response.raise_for_status()
        data = response.json()

        if data["status"] == "completed":
            return data["video_url"]
        elif data["status"] == "failed":
            raise Exception(data.get("error", "Video generation failed"))

        time.sleep(interval)

    raise TimeoutError("Video generation timed out")

授權

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