Create Task API

API Overview

Used to submit a 3D model split task and return a task ID.

Protocol	Endpoint	Method	Auth	Request Format	Response Format
HTTP	/open-api/v1/split/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 splitting. • Format: glb, stl, obj • Size: up to 200 MB • Count: 1 file
mesh_url	string	Yes, either with mesh	Input model URL for splitting. • Format: glb, stl, obj • Size: up to 200 MB • Count: 1 URL
model	string	No	Split model type. Default is character. Enum values: • character: character split with template and joint options • general: general model split
part	string	Required when model is character	Character split template. Default is a. Enum values: • a: 6 parts • b: 5 parts • c: 4 parts, excluding head • d: 4 parts, including head • e: 3 parts • f: 2 parts
joint	string	Required when model is character	Character joint type. Default is ball. Enum values: • none • ball • dovetail
level	string	Required when model is general	General split granularity. Default is medium. Enum values: • low • medium • high
format	int	No	Output model format. Default is 1. Character split currently supports 2 (glb) only. 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
	state	string	Initial task state. The create-task API returns queueing after successful submission
msg	-	string	Detailed error message

{
  "code": 200,
  "data": {
    "task_id": "split_20260312_8f92ab3e1cde",
    "state": "queueing"
  },
  "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)

Character Split

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

General Split

curl --location --request POST 'https://api.hitem3d.ai/open-api/v1/split/create-task' \
--header 'Authorization: Token {{token}}' \
--form 'mesh_url="https://client.example.com/models/demo.glb"' \
--form 'model="general"' \
--form 'level="medium"' \
--form 'format="2"'