Video & tư liệu
Lấy Trạng thái Video
Lấy trạng thái và kết quả của một tác vụ video
GET /v1/videos/generations/{id} là một endpoint tương thích. Nó vẫn được hỗ trợ cho các tích hợp hiện có và trả về kết quả theo cùng định dạng với GET /v1/tasks/{id}. Các tích hợp mới nên thực hiện poll GET /v1/tasks/{id}; xem Lấy Trạng thái Tác vụ.
Tham số Đường dẫn (Path Parameters)
ID tác vụ được trả về bởi yêu cầu tạo video. id và task_id xác định cùng một tác vụ.
Việc đọc trạng thái sẽ trả về HTTP 200 ngay cả khi tác vụ thất bại; hãy kiểm tra status. Một tác vụ đã hết hạn hoặc không khả dụng sẽ trả về 404 async_task_not_found. Một tác vụ không thuộc về workspace của bạn sẽ trả về 403 task_not_owned. Lỗi 503 async_task_owner_unavailable là tạm thời: hãy thử lại yêu cầu.
Phản hồi (Response)
Các trường mô tả kết quả, lỗi, dấu thời gian (timestamp) và model sẽ được trả về khi có sẵn cho tác vụ đó.
ID tác vụ.
ID tác vụ giống với id.
URL trạng thái cho tác vụ này. Hãy poll GET /v1/tasks/{id} với id.
ID giao dịch thanh toán sau khi quyết toán. Nó tách biệt với ID tác vụ.
Trạng thái tác vụ: pending, processing, completed, failed.
Tiến độ tùy chọn từ 0 đến 100. Chỉ được trả về khi có giá trị tiến độ thực tế; hãy sử dụng status để xác định việc hoàn thành.
URL của video đã tạo (khi hoàn thành). Đây là URL kết quả phương tiện của TokenLab có hiệu lực trong 30 ngày; xem Tải xuống kết quả. Các tác vụ thất bại hoặc chưa hoàn thành sẽ không trả về URL video.
URL của khung hình cuối cùng được tạo, khi bạn yêu cầu nó với return_last_frame và model hỗ trợ tính năng này.
Kết quả video đơn lẻ với url, duration, width và height khi có sẵn.
Nhiều kết quả video khi tác vụ trả về nhiều hơn một đầu ra.
Lý do tác vụ thất bại (chỉ khi status là failed): một chuỗi, hoặc một đối tượng chứa message và, khi biết, bao gồm type, code, param và retryable. Một tác vụ thất bại cũng có thể mang theo error_details; xem Các tác vụ bất đồng bộ và polling.
Trạng thái lưu trữ của video: days và items, mỗi mục bao gồm url, kind, status và expires_at. Nó có thể không xuất hiện khi trạng thái chưa được biết kịp thời; URL vẫn hoạt động.
Dấu thời gian tạo.
Dấu thời gian cập nhật lần cuối.
Model được sử dụng cho tác vụ.
Yêu cầu
curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
-H "Authorization: Bearer sk-your-api-key"Phản hồi
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"model": "veo3.1",
"created": 1706000000,
"updated": 1706000000
}Tải xuống kết quả
video_url có dạng https://api.tokenlab.sh/v1/media-results/{id}.mp4?token=…. Token trong URL là thông tin xác thực, vì vậy không cần header Authorization. Chỉ chia sẻ URL này với những người được phép xem video. URL sẽ chuyển hướng đến tệp, vì vậy hãy theo dõi các chuyển hướng khi bạn tải xuống (curl -L).
- Nó có hiệu lực trong 30 ngày kể từ khi kết quả được ghi lại lần đầu. Hãy tải tệp xuống nếu bạn cần lưu trữ lâu hơn; xem Lưu trữ dữ liệu.
404 media_not_found: token hoặc phần mở rộng tệp không khớp với kết quả. Hãy sử dụng chính xác URL bạn đã nhận được.410 media_expired: thời hạn 30 ngày đã kết thúc.502hoặc503 media_unavailable: kết quả vẫn đang được ghi lại, hoặc TokenLab đang bận. Hãy thử lại sau khoảng thời gianRetry-After.- Thêm
metadata=truevào URL để đọc trạng thái lưu thay vì tệp.
Một số kết quả được phân phối dưới dạng https://api.tokenlab.sh/v1/videos/generations/{id}/content. URL đó cần cùng header Authorization: Bearer mà bạn sử dụng để polling, và chỉ workspace sở hữu tác vụ mới có thể mở nó.
Khoảng thời gian Kiểm tra (Check Interval)
- Kiểm tra mỗi 5–10 giây.
- Tăng khoảng thời gian cho các tác vụ chạy lâu.
- Thiết lập thời gian chờ tối đa cho ứng dụng của bạn.
- Dừng lại khi trạng thái là
failedvà hiển thịerrorđược trả về.
import requests
import time
def wait_for_video(task_id, max_wait=600, interval=5):
"""Chờ video với thời gian chờ (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")Xác thực
BearerAuth Xác thực bằng Khóa API. Tạo hoặc quản lý khóa API trong Dashboard > API > API Keys.
Vị trí: header
Tham số đường dẫn
ID tác vụ async được trả về bởi id / task_id, hoặc được nhúng trong poll_url
Phản hồi
application/json
application/json
application/json
application/json
application/json
application/json
application/json