视频与素材
获取视频状态
获取视频生成任务的状态和结果
GET /v1/videos/generations/{id} 是兼容端点,继续保留,供现有集成使用,返回的结果格式与 GET /v1/tasks/{id} 相同。新集成请调用 GET /v1/tasks/{id},详见获取任务状态。
路径参数
创建视频时返回的任务 ID。id 和 task_id 指向同一个任务。
即使任务失败,状态查询也返回 HTTP 200,请检查 status。已过期或不可用的任务返回 404 async_task_not_found。不属于你的工作区的任务返回 403 task_not_owned。503 async_task_owner_unavailable 是暂时性错误,请重试。
响应
结果、错误、时间戳和模型字段仅在任务提供时返回。
任务 ID。
与 id 相同的任务 ID。
任务的状态地址(如有)。用 id 调用 GET /v1/tasks/{id} 查询。
结算完成后返回的账单交易 ID,与任务 ID 不同。
任务状态:pending、processing、completed、failed。
可选进度,范围 0 到 100。仅在任务提供真实进度时返回;请使用 status 判断任务是否完成。
生成视频的 URL(完成时)。它是 TokenLab 媒体结果 URL,有效期 30 天;参见下载结果。失败和未完成的任务不返回视频 URL。
最后一帧的 URL,仅当你用 return_last_frame 请求且模型支持时返回。
单个视频结果,包含 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):
"""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 API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。
位置: header
路径参数
由 id / task_id 返回或嵌入在 poll_url 中的异步任务 ID
响应
application/json
application/json
application/json
application/json
application/json
application/json
application/json