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: • pro: higher quality model (2K)
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
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 Example (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"'