TokenLab

3D

取得 3D 模型狀態

檢索 3D 生成任務的狀態與結果

GET
/v1/tasks/{id}

GET /v1/3d/generations/{id} 為相容性端點。現有的整合仍可繼續使用,但新的整合應輪詢 GET /v1/tasks/{id};請參閱 取得任務狀態。

呼叫 GET /v1/tasks/{id} 以檢查您的 3D 模型生成任務狀態。

id 與 task_id 指向同一個任務。

若公開任務已過期或無法存取,可能會回傳 404 async_task_not_found。若當前 API key 無法確認任務的所有權,回應將為 403 task_not_owned。

路徑參數 (Path Parameters)

idstringpath必填

3D 生成任務 ID。

回應 (Response)

當任務有相關結果、錯誤、時間戳記與模型資訊時,將會回傳這些欄位。

idstring

任務 ID。

task_idstring

非同步任務識別碼別名(若有提供)。

poll_urlstring

此任務的狀態 URL。請使用 id 輪詢 GET /v1/tasks/{id}。

statusstring

任務狀態:pending(待處理)、processing(處理中)、completed(已完成)、failed(失敗)或 timeout(逾時)。失敗的任務仍會回傳 HTTP 200。

progressinteger

選填的進度數值。僅在有實際進度數值時回傳;請使用 status 來判斷任務是否完成。

model_urlstring

下載 3D 模型檔案的 URL(完成時提供)。這是一個 TokenLab 媒體結果連結,有效期為 30 天。

glb_urlstring

下載 GLB 格式模型的 URL(可用時提供)。

fbx_urlstring

下載 FBX 格式模型的 URL(可用時提供)。

errorstring | object

錯誤訊息(失敗時提供)。

error_detailsobject

任務失敗時的詳細資訊:包含 status、message、type、code、retryable,以及當請求欄位出錯時的 param。

media_retentionobject

結果連結的保存狀態:包含 days 與 items[](內含 url、kind、status 與 expires_at)。此欄位可能不存在,但連結仍可正常運作。請參閱 資料保留。

請求

curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

回應

Response (Completed)
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "completed",
  "model_url": "https://api.tokenlab.sh/v1/media-results/5e2a7c90-1d4b-4f8e-a3c6-8b9d0e1f2a47.glb?token=…",
  "glb_url": "https://api.tokenlab.sh/v1/media-results/5e2a7c90-1d4b-4f8e-a3c6-8b9d0e1f2a47.glb?token=…",
  "fbx_url": "https://api.tokenlab.sh/v1/media-results/8d1b3f6a-9c2e-4a5d-b7e0-2f4c6a8e0d15.fbx?token=…",
  "media_retention": {
    "days": 30,
    "items": [
      {
        "url": "https://api.tokenlab.sh/v1/media-results/5e2a7c90-1d4b-4f8e-a3c6-8b9d0e1f2a47.glb?token=…",
        "kind": "3d",
        "content_type": "model/gltf-binary",
        "status": "saved",
        "expires_at": "2024-02-22T08:54:20.000Z"
      },
      {
        "url": "https://api.tokenlab.sh/v1/media-results/8d1b3f6a-9c2e-4a5d-b7e0-2f4c6a8e0d15.fbx?token=…",
        "kind": "3d",
        "content_type": "application/octet-stream",
        "status": "saved",
        "expires_at": "2024-02-22T08:54:20.000Z"
      }
    ]
  }
}

授權

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