查询任务接口

接口概述

用于根据任务 ID 查询模型分割任务的当前状态及结果。

网络协议	请求地址	请求方法	鉴权方式	请求格式	响应格式
HTTP	/open-api/v1/segmentation/query-task	GET	Token	application/json	application/json

请求头（Headers）

参数名称	值	描述
Content-Type	application/json	数据交换格式
Authorization	Token	将 {token} 替换为您获取到的 token

请求参数（HTTP GET）

参数名称	类型	必选	描述
task_id	string	是	创建任务接口返回的任务 ID

https://api.hitem3d.ai/open-api/v1/segmentation/query-task?task_id=segmentation_20260312_8f92ab3e1cde

响应体（Response）

参数名称	子字段	类型	描述
code	-	int	错误码，具体见错误码表
data	task_id	string	任务 ID
	state	string	处理状态 • created：任务已创建 • queueing：任务排队中 • processing：任务处理中 • success：任务成功 • failed：任务失败
	id	string	生成物 ID
	cover_url	string	生成物封面图 URL，有效期一小时
	url	string	生成结果 URL，有效期 1 小时
msg	-	string	具体错误信息

{
  "code": 200,
  "data": {
    "task_id": "segmentation_20260312_8f92ab3e1cde",
    "state": "success",
    "id": "segmentation_20260312_8f92ab3e1cde_0",
    "cover_url": "https://example.com/cover.png",
    "url": "https://example.com/segmentation/output/result.glb"
  },
  "msg": "success"
}

错误码（Error Code）

错误码按 JSON 结构返回，包含 code 和 msg 字段。

{
  "code": 5001001,
  "data": {},
  "msg": "generate failed"
}

错误码	错误信息	错误描述
5001001	generate failed	超时或模型解析失败，请重试；所耗积分已退还

请求示例（Shell）

curl --location --request GET 'https://api.hitem3d.ai/open-api/v1/segmentation/query-task?task_id=segmentation_20260312_8f92ab3e1cde' \
--header 'Authorization: Token {{token}}' \
--header 'Content-Type: application/json'