异步任务
获取任务状态
获取任何异步任务的状态和结果:图片、视频、音乐、3D、Worlds 和异步音频转写
概览
用 GET /v1/tasks/{id} 查询任何异步任务。图片、视频、音乐、3D、Worlds 和异步音频转写任务都适用。传入创建响应中的 id 或 task_id。
World 结果字段(如 world_id、world_marble_url)见 获取 World 状态。World 任务的 X-Task-Type 为 3d。
多数任务的创建响应中,poll_url 就是这个路径。Worlds 创建响应返回的 poll_url 位于 /v1/worlds/generations/{id};Worlds 也请用任务 id 调用 /v1/tasks/{id}。
按类型划分的状态路径(例如 /v1/images/{id}、/v1/videos/generations/{id}、/v1/music/generations/{id} 和 /v1/3d/generations/{id})是兼容端点,继续保留,供现有集成使用。
任务失败时,状态查询仍返回 HTTP 200。请读取 status,不要用 HTTP 状态码判断结果。结果字段随任务类型而异,见获取图像状态、获取视频状态、获取音乐状态和获取 3D 状态。结果链接是 TokenLab 媒体结果 URL,有效期 30 天,见数据保留。
路径参数
由 create 请求返回的 id 或 task_id。
响应
结果、错误、时间戳和模型字段仅在任务提供时返回。
TokenLab 任务 ID。
同一个任务 ID 的兼容字段名。
任务的状态地址(如有)。用 id 调用 GET /v1/tasks/{id} 查询。
任务有计费交易记录时返回的计费交易 ID。X-Billing-Transaction-ID 响应头的值相同。它是计费标识,不是任务标识。
任务状态:pending、processing、completed、failed 或 timeout。到 completed、failed 或 timeout 时停止轮询。已取消的任务会表示为 failed 并带有 cancelled: true。
排队中的异步任务在执行前被取消时为 true。
取消标记。取消成功时为 cancelled。
对于已完成的图片任务,生成的图片结果会在这里返回。图片任务会在 data[].url 中返回 URL。
可选进度值。仅在任务提供真实进度时返回;请使用 status 判断任务是否完成。
任务完成并生成视频时的结果资源 URL。
单个视频结果,可能包含 url、duration、width 和 height。
多个视频结果。
任务失败原因:字符串,或包含 message 以及(已知时)type、code、param、retryable 的对象。
任务失败时的失败详情:status、message、type、code、retryable,以及请求字段有误时的 param。
结果链接的保存状态:days 和 items[](含 url、kind、status、expires_at)。该字段可能不存在,链接仍可使用。
可用时的创建时间戳。
可用时的上次更新时间戳。
可用时任务使用的模型。
响应头
成功的状态响应包含以下响应头:
| 响应头 | 说明 |
|---|---|
X-Task-ID | 公开任务 ID |
X-Task-Type | 任务类型,例如 image、video、music、3d 或 audio |
Cache-Control | no-store,不要缓存状态响应 |
X-Billing-Transaction-ID | 有计费交易记录时返回的计费交易 ID |
X-Task-Cost | 任务结算后返回的结算费用 |
错误行为
| HTTP | 错误码 | 含义 |
|---|---|---|
400 | missing_task_id、invalid_task_id | 任务 ID 缺失或不是有效的任务 ID |
403 | task_not_owned | 任务不属于此 API 密钥所在的工作区,请停止轮询 |
404 | async_task_not_found | 任务已过期或不可用 |
503 | async_task_owner_unavailable | 暂时无法读取该任务,请重试 |
{
"error": {
"message": "Task not found or no longer available.",
"type": "invalid_request_error",
"code": "async_task_not_found"
}
}请求
curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
-H "Authorization: Bearer sk-your-api-key"{ "id": "string", "status": "pending", "progress": 0, "created": 0, "updated": 0, "model": "string", "video": { "url": "string", "duration": 0, "width": 0, "height": 0 }, "error": "string", "error_details": { "projection_version": 0, "status": 400, "message": "string", "type": "string", "code": "string", "param": "string", "retryable": true, "upstream": { "source": "string", "code": "string", "message": "string", "param": "string" } }, "task_id": "string", "poll_url": "string", "cancelled": true, "cancellation_status": "cancelled", "billing_transaction_id": "string", "video_url": "string", "last_frame_url": "string", "videos": [ {} ], "data": [ {} ], "audio_url": "string", "title": "string", "lyrics": "string", "model_url": "string", "glb_url": "string", "fbx_url": "string", "media_retention": { "days": 0, "items": [ { "url": "http://example.com", "kind": "image", "content_type": "string", "status": "saving", "expires_at": "2019-08-24T14:15:22Z" } ] }}授权
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