Query Task API

API Overview

Used to query the current status and result of a segmentation task by task ID.

Protocol	Endpoint	Method	Auth	Request Format	Response Format
HTTP	/open-api/v1/segmentation/query-task	GET	Token	application/json	application/json

Request Headers

Parameter	Value	Description
Content-Type	application/json	Data exchange format
Authorization	Token	Replace {token} with the token you obtained

Request Parameters (HTTP GET)

Parameter	Type	Required	Description
task_id	string	Yes	Task ID returned by the create-task API result

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

Response Body

Parameter	Field	Type	Description
code	-	int	Error code, see error code table
data	task_id	string	Task ID
	state	string	Processing status • created: task created • queueing: task queued • processing: task in progress • success: task completed • failed: task failed
	id	string	Generated artifact ID
	url	string	Generated result URL, valid for one hour
msg	-	string	Detailed error message

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

Error Codes

Error codes are returned in JSON structure, including code and msg.

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

Error Code	Error Message	Error Description
5001001	generate failed	Timeout or model parsing failed. Retry later; credits are refunded

Request Example (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'