Model Splitting
Create a task, then query its result by task ID. Each endpoint defines its own authentication and parameters.
Create task
POST https://api.hitem3d.ai/open-api/v1/split/create-task
Request headers
| Header | Value |
|---|---|
Authorization | Bearer <accessToken>. Use data.accessToken from Get token. |
| Content-Type | multipart/form-data (let the upload client generate the boundary) |
Request body
| Parameter | Type | Required | Parameter description |
|---|---|---|---|
mesh | file | Yes, choose either this or mesh_url | Upload one model to split. Supported formats: glb, stl, obj. Limit: 200 MB. |
mesh_url | string | Yes, choose either this or mesh | One URL of a model to split. The same format and size limits as mesh apply. |
model | string | No | Split model type. Defaults to character.character: character splitting with templates and joints.general: general model splitting. |
part | string | Required for model=character | Character split template. Defaults to a.a: 6 parts. b: 5 parts.c: 4 parts without the head. d: 4 parts with the head.e: 3 parts. f: 2 parts. |
joint | string | Required for model=character | Character joint type. Defaults to ball.Values: none, ball, dovetail, pin. |
merge | string | Required when joint is ball, dovetail or pin | Merge joints with the body. Defaults to yes (merge). Use no to keep them separate. |
level | string | Required for model=general | General split detail level. Defaults to medium.Values: low, medium, high. |
format | int | No | One output format per task. Default: 1 (obj).1: obj2: glb3: stl4: fbx5: usdz6: 3mf |
Response body
| Field | Type | Description |
|---|---|---|
code | int | Response code as defined by this endpoint |
data.task_id | string | Task ID |
data.state | string | Returns queueing on successful creation |
msg | string | Message |
Configure a Webhook in Console to receive task notifications. You can also poll the query endpoint.
Request example
bash
curl --request POST 'https://api.hitem3d.ai/open-api/v1/split/create-task' \
--header "Authorization: Bearer $HI3D_TOKEN" \
--form 'mesh=@./model.glb' \
--form 'model=general' \
--form 'level=medium' \
--form 'format=2'python
import os
import requests
data = {
"model": "general",
"level": "medium",
"format": "2",
}
with open("model.glb", "rb") as file_0:
files = [
("mesh", ("model.glb", file_0)),
]
response = requests.post(
"https://api.hitem3d.ai/open-api/v1/split/create-task",
headers={"Authorization": "Bearer " + os.environ["HI3D_TOKEN"]},
data=data,
files=files,
)
response.raise_for_status()
print(response.json())Response example
json
{
"code": 200,
"data": {
"task_id": "<TASK_ID>",
"state": "queueing"
},
"msg": "success"
}Error codes
| code | Message | Description |
|---|---|---|
| 5001001 | generate failed | Generation timed out or input parsing failed; consumed credits were returned. Check the original task and input before deciding whether to submit a new task. |
Service process → · Webhook guide → · Credit pricing →
API support:apicontact@hi3d.ai
Query task
Keep the task_id returned at submission and use the Model Splitting route in Query task.
API support:apicontact@hi3d.ai