创建任务接口

接口概述

根据输入的单张图片生成深度图。

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

请求头（Headers）

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

请求体（HTTP Form 表单提交）

参数名称	类型	必填	参数描述
image	file	是，跟 image_url 二选一	用于生成深度图的输入图片。 • 格式：png、jpeg、jpg、webp • 大小：不超过 20 MB • 数量：1 张
image_url	string	是，跟 image 二选一	用于生成深度图的输入图片 URL。 • 格式：png、jpeg、jpg、webp • 大小：不超过 20 MB • 数量：1 个 URL
model_type	string	是	深度图生成模型类型，默认 pro。 枚举值： • pro：高质量模型（2K）
rmbg	int	是	去除背景开关，默认 1。 枚举值： • 0：关闭 • 1：开启
response_format	string	否	返回结果格式，默认 url。
format	int	是	深度图输出格式。 枚举值： • 1：exr • 2：png
callback_url	string	否	回调地址。任务状态变更时，Hitem3D 以 POST 回调，回调结构与查询任务接口返回体一致。 回调状态包括： • success • failed

响应体（Response）

参数名称	子字段	类型	描述
code	-	int	错误码，具体见错误码表
data	task_id	string	Hitem3D 生成的异步任务 ID，后续通过查询任务接口获取结果
msg	-	string	具体错误信息

{
  "code": 200,
  "data": {
    "task_id": "depth_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/depth/create-task' \
--header 'Authorization: Bearer {{accessToken}}' \
--form 'image=@"/path/to/demo.jpg"' \
--form 'format="1"' \
--form 'response_format="url"' \
--form 'callback_url="https://client.example.com/webhook/depth"'