创建任务接口

接口概述

用于提交 3D 模型拆件任务，返回任务 ID。

网络协议	请求地址	请求方法	鉴权方式	请求格式	响应格式
HTTP	/open-api/v1/split/create-task	POST	Bearer	multipart/form-data	application/json

请求头（Headers）

参数名称	值	描述
Content-Type	multipart/form-data	数据交换格式
Authorization	Bearer	将 {token} 替换为您获取到的 token

请求体（HTTP Form 表单提交）

参数名称	类型	必填	参数描述
mesh	file	是，跟 mesh_url 二选一	上传待拆件模型文件。 • 格式：glb、stl、obj • 大小：不超过 200 MB • 数量：1 个
mesh_url	string	是，跟 mesh 二选一	待拆件模型 URL。 • 格式：glb、stl、obj • 大小：不超过 200 MB • 数量：1 个
model	string	否	拆件模型类型，默认 character。 可选值： • character：角色拆件，支持模板与连接件参数 • general：通用模型拆件
part	string	model 为 character 时必填	角色拆件模板，默认 a。 可选值： • a：6 parts • b：5 parts • c：4 parts，不含头部 • d：4 parts，包含头部 • e：3 parts • f：2 parts
joint	string	model 为 character 时必填	角色连接件类型，默认 ball。 可选值： • none • ball • dovetail • pin
merge	string	joint 为 ball、dovetail、pin 时必填	是否将连接件与主体融合，默认 yes。 可选值： • yes • no
level	string	model 为 general 时必填	通用拆件精细度，默认 medium。 可选值： • low • medium • high
format	int	否	生成模型的格式，仅限制一种生成格式，默认为 1（obj）。 枚举值： • 1：obj • 2：glb • 3：stl • 4：fbx • 5：usdz • 6：3mf
callback_url	string	否	回调地址。任务状态变化时，Hi3D 会以 POST 回调，回调结构与查询任务接口一致，状态包括 success、failed。

响应体（Response）

参数名称	子字段	类型	描述
code	-	int	错误码，具体见错误码表
data	task_id	string	Hi3D 生成的异步任务 ID，用于后续查询任务状态和结果
	state	string	初始任务状态。创建成功后返回 queueing
msg	-	string	具体错误信息

{
  "code": 200,
  "data": {
    "task_id": "split_20260312_8f92ab3e1cde",
    "state": "queueing"
  },
  "msg": "success"
}

错误码（Error Code）

错误码按 JSON 结构返回，包含 code 和 msg 字段。

{
  "code": 5001001,
  "data": {},
  "msg": "generate failed"
}

错误码	错误信息	错误描述
200	-	任务创建成功
5001001	generate failed	超时或模型解析失败，请重试；所耗积分已退还

请求示例（Shell）

角色拆件

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

通用拆件

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