Create Task API

API Overview

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

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

The create endpoint uses muilticolor as shown above. Keep this spelling when making requests.

Request Headers

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

Request Body (HTTP Form Submission)

Parameter	Type	Required	Description
mesh	file	Yes, either with mesh_url	Input textured model file. • Format: glb • Size: up to 200 MB • Count: 1 file
mesh_url	string	Yes, either with mesh	Publicly accessible input textured model URL. • Format: glb • Size: up to 200 MB • Count: 1 URL
model	string	No	Model version. Only multicolor is supported.
number_color	int	No	Controls the number of colors in the model. If you need to modify the model colors later, 0 (max) is recommended. Default: 4. Enum values: 1, 2, 3, 4, 5, 6, 7, 8, 0 (max).
format	int	No	Generated model format. Only one output format can be generated. Default: 1 (obj). Enum values: • 1: obj • 2: glb • 3: stl (Not currently supported) • 4: fbx • 5: usdz (Not currently supported) • 6: 3mf (Not currently supported)
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": "multicolor_20260715_8f92ab3e1cde",
    "state": "queueing"
  },
  "msg": "success"
}

Error Codes

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/muilticolor/create-task' \
--header 'Authorization: Bearer {{token}}' \
--form 'mesh=@"/path/to/demo.glb"' \
--form 'model="multicolor"' \
--form 'number_color=4' \
--form 'format=1' \
--form 'callback_url="https://client.example.com/webhook/multicolor"'