拆件
提交生成任务并使用任务 ID 查询结果。每个端点的鉴权与参数分别定义。
创建任务
POST https://api.hitem3d.ai/open-api/v1/split/create-task
请求头
| Header | 值 |
|---|---|
Authorization | Bearer <accessToken>。令牌取自获取 Token接口返回的 data.accessToken。 |
| Content-Type | multipart/form-data(文件上传时由客户端生成boundary) |
请求体
| 参数 | 类型 | 必填 | 参数描述 |
|---|---|---|---|
mesh | file | 是,与 mesh_url 二选一 | 上传 1 个待拆件模型文件。 支持 glb、stl、obj,不超过 200 MB。 |
mesh_url | string | 是,与 mesh 二选一 | 输入 1 个待拆件模型 URL。格式及大小限制同 mesh。 |
model | string | 否 | 拆件模型类型,默认 character。character:角色拆件,支持模板和连接件。general:通用模型拆件。 |
part | string | model=character 时必填 | 角色拆件模板,默认 a。a:6 件,b:5 件。c:4 件(不含头部),d:4 件(含头部)。e:3 件,f:2 件。 |
joint | string | model=character 时必填 | 角色连接件类型,默认 ball。可选 none、ball、dovetail、pin。 |
merge | string | joint 为 ball、dovetail 或 pin 时必填 | 是否将连接件与主体融合。默认 yes(融合),no 为不融合。 |
level | string | model=general 时必填 | 通用拆件精细度,默认 medium。可选 low、medium、high。 |
format | int | 否 | 每次生成一种格式,默认 1(obj)。1:obj2:glb3:stl4:fbx5:usdz6:3mf |
响应体
| Field | Type | 说明 |
|---|---|---|
code | int | 响应码,按本端点定义 |
data.task_id | string | 任务ID |
data.state | string | 创建成功返回queueing |
msg | string | 具体消息 |
在控制台配置 Webhook 可接收任务通知,也可使用查询接口轮询。
请求示例
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())响应示例
json
{
"code": 200,
"data": {
"task_id": "<TASK_ID>",
"state": "queueing"
},
"msg": "success"
}错误码
| code | 错误消息 | 说明 |
|---|---|---|
| 5001001 | generate failed | 生成超时或输入解析失败,所耗积分已退还。先检查原任务和输入,再决定是否创建新任务。 |
服务流程 → · Webhook说明 → · 查看积分计费 →
技术支持:apicontact@hi3d.ai
查询任务
提交后保存 task_id,按查询任务中的「拆件」路径读取结果。
技术支持:apicontact@hi3d.ai