Create Task API

API Overview

Generate a depth map from one input image.

Protocol	Endpoint	Method	Auth	Request Format	Response Format
HTTP	/open-api/v1/depth/create-task	POST	Bearer	multipart/form-data	application/json

Request Headers

Parameter	Value	Description
Content-Type	multipart/form-data	Data exchange format
Authorization	Bearer	Replace {accessToken} with the accessToken obtained above

Request Body (HTTP Form Submission)

Parameter	Type	Required	Description
image	file	Yes, either with image_url	Input image used for depth map generation. • Format: png, jpeg, jpg, webp • Size: max 20 MB • Count: 1 file
image_url	string	Yes, either with image	Input image URL used for depth map generation. • Format: png, jpeg, jpg, webp • Size: max 20 MB • Count: 1 URL
model_type	string	Yes	Model type for depth generation quality. Default is pro. Enum values: • base: standard quality model (1K) • pro: higher quality model (2K)
height_relief	BigDecimal	No	Relief height. Default is 1.3. Allowed values: 0.1–50.0
rmbg	int	Yes	Remove background switch. Default is 1. Enum values: • 0: disabled • 1: enabled
degree_rmbg	BigDecimal	No	Available when rmbg=1. Background removal strength. Default is 0.02. Allowed values: 0.00–1.00, hundredths only
shape_base	int	No	Available when rmbg=0. Base shape. Default is 0 (square). Enum values: • 0: square • 1: circle
thickness_base	string	No	Available when rmbg=0. Base thickness in mm. Default is 1.0. Allowed values: 0.1–20.0, tenths only
width	int	No	Width in mm. Default is 40. Allowed values: 20–600
sculpmode	int	No	Sculpt mode. Default is 0 (emboss). Enum values: • 0: emboss • 1: engrave
response_format	string	No	Return format of generation result. Default is url.
format	int	Yes	Depth map output format. Enum values: • 1: exr • 2: png • 3: stl • 4: glb • 5: 3mf • 6: bmp Note: 6 means bmp for this endpoint; the general Image to 3D endpoint uses 6=3mf.
callback_url	string	No	Callback endpoint for task status changes. Request method is POST and callback payload matches query-task response structure. Callback states include: • success • failed

Response Body

Parameter	Field	Type	Description
code	-	int	Error code, see error code table
data	task_id	string	Asynchronous task ID generated by Hi3D, used to query task result afterward
msg	-	string	Detailed error message

{
  "code": 200,
  "data": {
    "task_id": "depth_20260312_8f92ab3e1cde"
  },
  "msg": "success"
}

Error Codes

Error codes are returned in JSON structure, including code and msg.

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

Error Code	Error Message	Error Description
200	-	Task created successfully
5001001	generate failed	Timeout or model failed to parse the input image. Retry later; credits are refunded

Request Examples (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())