创建任务接口

接口概述

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

网络协议	请求地址	请求方法	鉴权方式	请求格式	响应格式
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。 枚举值： • base：标准质量模型（1K） • pro：高质量模型（2K）
height_relief	BigDecimal	否	浮雕高度，默认 1.3。 可选值：0.1～50.0
rmbg	int	是	去除背景开关，默认 1。 枚举值： • 0：关闭 • 1：开启
degree_rmbg	BigDecimal	否	当 rmbg=1 时可使用。去除背景程度，默认 0.02。 可选值：0.00～1.00，仅支持百分位
shape_base	int	否	当 rmbg=0 时可使用。底座形状，默认 0（square）。 可选值： • 0：square • 1：circle
thickness_base	string	否	当 rmbg=0 时可使用。底座厚度，默认 1.0，单位 mm。 可选值：0.1～20.0，仅支持十分位
width	int	否	宽度，默认 40，单位 mm。 可选值：20～600
sculpmode	int	否	雕刻模式，默认 0（emboss）。 可选值： • 0：emboss • 1：engrave
response_format	string	否	返回结果格式，默认 url。
format	int	是	深度图输出格式。 枚举值： • 1：exr • 2：png • 3：stl • 4：glb • 5：3mf • 6：bmp 注意：此接口的 6 表示 bmp，与通用图生 3D 接口的 6=3mf 不同。
callback_url	string	否	回调地址。任务状态变更时，Hi3D 以 POST 回调，回调结构与查询任务接口返回体一致。 回调状态包括： • success • failed

响应体（Response）

参数名称	子字段	类型	描述
code	-	int	错误码，具体见错误码表
data	task_id	string	Hi3D 生成的异步任务 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 & Python）

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 'model_type="base"' \
--form 'height_relief="1.3"' \
--form 'format="6"' \
--form 'response_format="url"' \
--form 'callback_url="https://client.example.com/webhook/depth"'

import requests

url = "https://api.hitem3d.ai/open-api/v1/depth/create-task"
headers = {"Authorization": "Bearer {{accessToken}}"}
data = {
    "model_type": "base",
    "height_relief": "1.3",
    "format": "6",
    "response_format": "url",
}

with open("/path/to/demo.jpg", "rb") as image:
    response = requests.post(url, headers=headers, data=data, files={"image": image})
response.raise_for_status()
print(response.json())