创建任务接口

接口概述

用于提交 3D 模型多色任务，返回任务 ID。

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

创建接口路径使用上述 muilticolor 拼写，调用时请保持一致。

请求头（Headers）

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

请求体（HTTP Form 表单提交）

参数名称	类型	必填	参数描述
mesh	file	是，跟 mesh_url 二选一	上传带纹理的模型文件。 • 格式：glb • 大小：不超过 200 MB • 数量：1 个
mesh_url	string	是，跟 mesh 二选一	可公开访问的带纹理模型 URL。 • 格式：glb • 大小：不超过 200 MB • 数量：1 个
model	string	否	模型版本，仅支持 multicolor。
number_color	int	否	用于控制模型的颜色数量，若后续需要修改模型色彩，建议选择 0（max）。 默认：4。 可选值：1、2、3、4、5、6、7、8、0（max）。
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": "multicolor_20260715_8f92ab3e1cde",
    "state": "queueing"
  },
  "msg": "success"
}

错误码（Error Code）

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

请求示例（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"'