Create Task API

API Overview

Used to submit a model segmentation task and return a task ID.

Protocol	Endpoint	Method	Auth	Request Format	Response Format
HTTP	/open-api/v1/segmentation/create-task	POST	Token	multipart/form-data	application/json

Request Headers

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

Request Body (HTTP Form Submission)

Parameter	Type	Required	Description
mesh	file	Yes, either with mesh_url	Input model file for segmentation. • Format: glb, stl, obj • Size: up to 200 MB • Count: 1 file
mesh_url	string	Yes, either with mesh	Input model URL for segmentation. • Format: glb, stl, obj • Size: up to 200 MB • Count: 1 URL
seg_level	string	Yes	Segmentation granularity level. Enum values: • low • medium (default) • high
format	int	Yes	Output model format. Enum values: • 1: obj • 2: glb • 3: stl • 4: fbx • 5: usdz
callback_url	string	No	Callback endpoint for task status updates. Callback uses POST and follows the same response structure as query-task. States include success and failed.

Response Body

Parameter	Field	Type	Description
code	-	int	Error code, see error code table
data	task_id	string	Asynchronous task ID used to query task status and result
msg	-	string	Detailed error message

{
  "code": 200,
  "data": {
    "task_id": "segmentation_20260312_8f92ab3e1cde"
  },
  "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
200	-	Task created successfully
5001001	generate failed	Timeout or model parsing failed. Retry later; credits are refunded

Request Example (Shell)

curl --location --request POST 'https://api.hitem3d.ai/open-api/v1/segmentation/create-task' \
--header 'Authorization: Token {{token}}' \
--form 'mesh=@"/path/to/demo.glb"' \
--form 'seg_level="medium"' \
--form 'format="2"' \
--form 'callback_url="https://client.example.com/webhook/segmentation"'