TokenLab

視頻與素材

取得影片狀態

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

GET
/v1/tasks/{id}

GET /v1/videos/generations/{id} 為相容性端點。它仍支援現有的整合,並以與 GET /v1/tasks/{id} 相同的格式回傳結果。新的整合請輪詢 GET /v1/tasks/{id};請參閱 取得任務狀態。

路徑參數 (Path Parameters)

idstringpath必填

建立影片請求所回傳的任務 ID。id 與 task_id 指向同一個任務。

即使任務失敗,狀態讀取仍會回傳 HTTP 200;請檢查 status 欄位。已過期或無法取得的任務會回傳 404 async_task_not_found。不屬於您工作區的任務會回傳 403 task_not_owned。503 async_task_owner_unavailable 為暫時性錯誤:請重試請求。

回應 (Response)

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

idstring

任務 ID。

task_idstring

與 id 相同的任務 ID。

poll_urlstring

此任務的狀態 URL。請使用 id 輪詢 GET /v1/tasks/{id}。

billing_transaction_idstring

結算後的帳務交易 ID。它與任務 ID 是分開的。

statusstring

任務狀態:pending(待處理)、processing(處理中)、completed(已完成)、failed(失敗)。

progressinteger

選填,進度從 0 到 100。僅在有實際進度數值時回傳;請使用 status 來判斷是否完成。

video_urlstring

已生成影片的 URL(完成時)。這是一個 TokenLab 媒體結果 URL,有效期為 30 天;請參閱 下載結果。失敗或未完成的任務不會回傳影片 URL。

last_frame_urlstring

當您要求 return_last_frame 且模型支援時,會回傳最後生成的影格 URL。

videoobject

單一影片結果,包含 url、duration、width 與 height(若可用)。

videosarray

當任務回傳多個輸出時的多個影片結果。

errorstring | object

任務失敗的原因(僅在 status 為 failed 時):字串,或包含 message 的物件,若已知則包含 type、code、param 與 retryable。失敗的任務也可能帶有 error_details;請參閱 非同步作業與輪詢。

media_retentionobject

影片的儲存狀態:包含 days 與 items,每個項目都有 url、kind、status 與 expires_at。當狀態未及時得知時,此欄位可能不存在;但 URL 仍然有效。

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
}

下載結果

video_url 的格式類似 https://api.tokenlab.sh/v1/media-results/{id}.mp4?token=…。URL 中的 token 即為憑證,因此不需要 Authorization 標頭。請僅與可以觀看影片的人分享此 URL。該 URL 會重新導向至檔案,因此下載時請務必跟隨重新導向(例如使用 curl -L)。

  • 自結果首次記錄起,有效期為 30 天。若您需要長期保存,請下載該檔案;請參閱 資料保留。
  • 404 media_not_found:token 或副檔名與結果不符。請使用您收到的確切 URL。
  • 410 media_expired:30 天期限已過。
  • 502 或 503 media_unavailable:結果仍在記錄中,或 TokenLab 忙碌中。請在 Retry-After 指定的延遲後重試。
  • 在 URL 後加上 metadata=true 可讀取儲存狀態,而非下載檔案。

部分結果會以 https://api.tokenlab.sh/v1/videos/generations/{id}/content 的形式提供。該 URL 需要與您輪詢時使用的相同 Authorization: Bearer 標頭,且僅有擁有該任務的工作區可以開啟。

檢查間隔

  • 每 5–10 秒檢查一次。
  • 針對長時間執行的任務,請增加檢查間隔。
  • 為您的應用程式設定最大等待時間。
  • 當狀態為 failed 時請停止輪詢,並顯示回傳的 error。
import requests
import time

def wait_for_video(task_id, max_wait=600, interval=5):
    """等待影片完成,包含逾時機制。"""
    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", "影片生成失敗"))

        time.sleep(interval)

    raise TimeoutError("影片生成逾時")

授權

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