异步任务

获取任务状态

获取任何异步任务的状态和结果:图片、视频、音乐、3D、Worlds 和异步音频转写

GET
/v1/tasks/{id}

概览

用 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 天,见数据保留。

路径参数

idstringpath必填

由 create 请求返回的 id 或 task_id。

响应

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

idstring

TokenLab 任务 ID。

task_idstring

同一个任务 ID 的兼容字段名。

poll_urlstring

任务的状态地址(如有)。用 id 调用 GET /v1/tasks/{id} 查询。

billing_transaction_idstring

任务有计费交易记录时返回的计费交易 ID。X-Billing-Transaction-ID 响应头的值相同。它是计费标识,不是任务标识。

statusstring

任务状态:pending、processing、completed、failed 或 timeout。到 completed、failed 或 timeout 时停止轮询。已取消的任务会表示为 failed 并带有 cancelled: true。

cancelledboolean

排队中的异步任务在执行前被取消时为 true。

cancellation_statusstring

取消标记。取消成功时为 cancelled。

dataarray

对于已完成的图片任务,生成的图片结果会在这里返回。图片任务会在 data[].url 中返回 URL。

progressnumber

可选进度值。仅在任务提供真实进度时返回;请使用 status 判断任务是否完成。

video_urlstring

任务完成并生成视频时的结果资源 URL。

videoobject

单个视频结果,可能包含 url、duration、width 和 height。

videosarray

多个视频结果。

errorstring | object

任务失败原因:字符串,或包含 message 以及(已知时)type、code、param、retryable 的对象。

error_detailsobject

任务失败时的失败详情:status、message、type、code、retryable,以及请求字段有误时的 param。

media_retentionobject

结果链接的保存状态:days 和 items[](含 url、kind、status、expires_at)。该字段可能不存在,链接仍可使用。

createdinteger

可用时的创建时间戳。

updatedinteger

可用时的上次更新时间戳。

modelstring

可用时任务使用的模型。

响应头

成功的状态响应包含以下响应头:

响应头说明
X-Task-ID公开任务 ID
X-Task-Type任务类型,例如 image、video、music、3d 或 audio
Cache-Controlno-store,不要缓存状态响应
X-Billing-Transaction-ID有计费交易记录时返回的计费交易 ID
X-Task-Cost任务结算后返回的结算费用

错误行为

HTTP错误码含义
400missing_task_id、invalid_task_id任务 ID 缺失或不是有效的任务 ID
403task_not_owned任务不属于此 API 密钥所在的工作区,请停止轮询
404async_task_not_found任务已过期或不可用
503async_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
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