TokenLab

非同步任務

取得任務狀態

檢索任何非同步任務的狀態與結果:圖像、影片、音樂、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 的建立回應會在 /v1/worlds/generations/{id} 下回傳一個 poll_url;對於 Worlds,同樣請輪詢 /v1/tasks/{id} 並使用該任務的 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必填

建立請求所回傳的 id 或 task_id。

回應

當任務可用時,會回傳描述結果、錯誤、時間戳記與模型的欄位。

idstring

標準非同步任務識別碼。

task_idstring

非同步任務識別碼別名。

poll_urlstring

此任務的狀態 URL。請使用 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 金鑰。

位置: header

路徑參數

id*string

由 id / task_id 回傳,或嵌入於 poll_url 中的非同步任務 ID

回應

application/json

application/json

application/json

application/json

application/json

application/json

application/json