视频与素材

获取视频状态

获取视频生成任务的状态和结果

GET
/v1/tasks/{id}

GET /v1/videos/generations/{id} 是兼容端点,继续保留,供现有集成使用,返回的结果格式与 GET /v1/tasks/{id} 相同。新集成请调用 GET /v1/tasks/{id},详见获取任务状态。

路径参数

idstringpath必填

创建视频时返回的任务 ID。id 和 task_id 指向同一个任务。

即使任务失败,状态查询也返回 HTTP 200,请检查 status。已过期或不可用的任务返回 404 async_task_not_found。不属于你的工作区的任务返回 403 task_not_owned。503 async_task_owner_unavailable 是暂时性错误,请重试。

响应

结果、错误、时间戳和模型字段仅在任务提供时返回。

idstring

任务 ID。

task_idstring

与 id 相同的任务 ID。

poll_urlstring

任务的状态地址(如有)。用 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

最后一帧的 URL,仅当你用 return_last_frame 请求且模型支持时返回。

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):
    """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 Key。

位置: header

路径参数

id*string

由 id / task_id 返回或嵌入在 poll_url 中的异步任务 ID

响应

application/json

application/json

application/json

application/json

application/json

application/json

application/json