Image to Relief
Create a task, then query its result by task ID. Each endpoint defines its own authentication and parameters.
Create task
POST https://api.hitem3d.ai/open-api/v1/depth/create-task
Request headers
| Header | Value |
|---|---|
Authorization | Bearer <accessToken>. Use data.accessToken from Get token. |
| Content-Type | multipart/form-data (let the upload client generate the boundary) |
Request body
| Parameter | Type | Required | Parameter description |
|---|---|---|---|
image | file | Yes, choose either this or image_url | Upload one image to generate the depth map. Supported formats: png, jpeg, jpg, webp. Limit: 20 MB. |
image_url | string | Yes, choose either this or image | One input image URL. The same format and size limits as image apply. |
model_type | string | Yes | Depth map resolution tier. Defaults to pro.base: standard quality (1K).pro: high quality (2K). |
height_relief | BigDecimal | No | Relief height. Defaults to 1.3. Range: 0.1–50.0. |
rmbg | int | Yes | Background removal. Default: 1.1: On0: Off |
degree_rmbg | BigDecimal | No | Background removal strength. Defaults to 0.02. Range: 0.00–1.00 in hundredths.Available only with rmbg=1. |
shape_base | int | No | Base shape. Default: 0. Only available with rmbg=0.0: square1: circle |
thickness_base | string | No | Base thickness. Defaults to 1.0 mm. Range: 0.1–20.0 mm in tenths.Available only with rmbg=0. |
width | int | No | Output width. Defaults to 40 mm. Range: 20–600 mm. |
sculpmode | int | No | Sculpting mode. Default: 0.0: emboss1: engrave |
response_format | string | No | Response format. Defaults to url. |
format | int | Yes | Depth map output format.1: exr2: png3: stl4: glb5: 3mf6: bmp7: objNote: 6 selects bmp for relief and 3mf for general image-to-3D. |
Response body
| Field | Type | Description |
|---|---|---|
code | int | Response code as defined by this endpoint |
data.task_id | string | Task ID |
msg | string | Message |
Configure a Webhook in Console to receive task notifications. You can also poll the query endpoint.
Request example
bash
curl --request POST 'https://api.hitem3d.ai/open-api/v1/depth/create-task' \
--header "Authorization: Bearer $HI3D_TOKEN" \
--form 'image=@./input.png' \
--form 'model_type=pro' \
--form 'rmbg=1' \
--form 'format=4'python
import os
import requests
data = {
"model_type": "pro",
"rmbg": "1",
"format": "4",
}
with open("input.png", "rb") as file_0:
files = [
("image", ("input.png", file_0)),
]
response = requests.post(
"https://api.hitem3d.ai/open-api/v1/depth/create-task",
headers={"Authorization": "Bearer " + os.environ["HI3D_TOKEN"]},
data=data,
files=files,
)
response.raise_for_status()
print(response.json())Response example
json
{
"code": 200,
"data": {
"task_id": "<TASK_ID>"
},
"msg": "success"
}Error codes
| code | Message | Description |
|---|---|---|
| 5001001 | generate failed | Generation timed out or input parsing failed; consumed credits were returned. Check the original task and input before deciding whether to submit a new task. |
Service process → · Webhook guide → · Credit pricing →
API support:apicontact@hi3d.ai
Query task
Keep the task_id returned at submission and use the Image to Relief route in Query task.
API support:apicontact@hi3d.ai