視頻與素材
取得影片狀態
取得影片任務的狀態與結果
GET /v1/videos/generations/{id} 為相容性端點。它仍支援現有的整合,並以與 GET /v1/tasks/{id} 相同的格式回傳結果。新的整合請輪詢 GET /v1/tasks/{id};請參閱 取得任務狀態。
路徑參數 (Path Parameters)
建立影片請求所回傳的任務 ID。id 與 task_id 指向同一個任務。
即使任務失敗,狀態讀取仍會回傳 HTTP 200;請檢查 status 欄位。已過期或無法取得的任務會回傳 404 async_task_not_found。不屬於您工作區的任務會回傳 403 task_not_owned。503 async_task_owner_unavailable 為暫時性錯誤:請重試請求。
回應 (Response)
當任務有相關資訊時,會回傳描述結果、錯誤、時間戳記與模型的欄位。
任務 ID。
與 id 相同的任務 ID。
此任務的狀態 URL。請使用 id 輪詢 GET /v1/tasks/{id}。
結算後的帳務交易 ID。它與任務 ID 是分開的。
任務狀態:pending(待處理)、processing(處理中)、completed(已完成)、failed(失敗)。
選填,進度從 0 到 100。僅在有實際進度數值時回傳;請使用 status 來判斷是否完成。
已生成影片的 URL(完成時)。這是一個 TokenLab 媒體結果 URL,有效期為 30 天;請參閱 下載結果。失敗或未完成的任務不會回傳影片 URL。
當您要求 return_last_frame 且模型支援時,會回傳最後生成的影格 URL。
單一影片結果,包含 url、duration、width 與 height(若可用)。
當任務回傳多個輸出時的多個影片結果。
任務失敗的原因(僅在 status 為 failed 時):字串,或包含 message 的物件,若已知則包含 type、code、param 與 retryable。失敗的任務也可能帶有 error_details;請參閱 非同步作業與輪詢。
影片的儲存狀態:包含 days 與 items,每個項目都有 url、kind、status 與 expires_at。當狀態未及時得知時,此欄位可能不存在;但 URL 仍然有效。
建立時間戳記。
最後更新時間戳記。
任務所使用的模型。
請求
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 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