3D

获取 3D 模型状态

获取 3D 生成任务的状态和结果

GET
/v1/tasks/{id}

GET /v1/3d/generations/{id} 是兼容端点,继续保留,供现有集成使用。新集成请调用 GET /v1/tasks/{id},详见获取任务状态。

使用创建响应中的任务 ID 调用 GET /v1/tasks/{id},查询进度和结果。

id 和 task_id 标识同一任务。

已过期或不可用的公开任务可能返回 404 async_task_not_found。无法确认当前 API 密钥对任务的归属权限时,返回 403 task_not_owned。

路径参数

idstringpath必填

3D 生成任务 ID。

响应

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

idstring

任务 ID。

task_idstring

返回时与 id 对应的同一异步任务标识。

poll_urlstring

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

位置: header

路径参数

id*string

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

响应

application/json

application/json

application/json

application/json

application/json

application/json

application/json