创建任务接口

接口概述

用于提交模型分割任务，返回任务 ID。

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

请求头（Headers）

参数名称	值	描述
Content-Type	multipart/form-data	数据交换格式
Authorization	Token	将 {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 个
seg_level	string	是	分割精细度。 可选值： • low • medium（默认） • high
format	int	是	输出模型格式。 可选值： • 1：obj • 2：glb • 3：stl • 4：fbx • 5：usdz
callback_url	string	否	回调地址。任务状态变化时，Hi3D 会以 POST 回调，回调结构与查询任务接口一致，状态包括 success、failed。

响应体（Response）

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

{
  "code": 200,
  "data": {
    "task_id": "segmentation_20260312_8f92ab3e1cde"
  },
  "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/segmentation/create-task' \
--header 'Authorization: Token {{token}}' \
--form 'mesh=@"/path/to/demo.glb"' \
--form 'seg_level="medium"' \
--form 'format="2"' \
--form 'callback_url="https://client.example.com/webhook/segmentation"'