图生浮雕
提交生成任务并使用任务 ID 查询结果。每个端点的鉴权与参数分别定义。
创建任务
POST https://api.hitem3d.ai/open-api/v1/depth/create-task
请求头
| Header | 值 |
|---|---|
Authorization | Bearer <accessToken>。令牌取自获取 Token接口返回的 data.accessToken。 |
| Content-Type | multipart/form-data(文件上传时由客户端生成boundary) |
请求体
| 参数 | 类型 | 必填 | 参数描述 |
|---|---|---|---|
image | file | 是,与 image_url 二选一 | 上传 1 张用于生成深度图的图片。 支持 png、jpeg、jpg、webp,不超过 20 MB。 |
image_url | string | 是,与 image 二选一 | 输入 1 个图片 URL。格式及大小限制同 image。 |
model_type | string | 是 | 深度图的分辨率档位,默认 pro。base:标准质量(1K)。pro:高质量(2K)。 |
height_relief | BigDecimal | 否 | 浮雕高度,默认 1.3。范围 0.1–50.0。 |
rmbg | int | 是 | 去背景开关,默认 1。1:开启0:关闭 |
degree_rmbg | BigDecimal | 否 | 去背景程度,默认 0.02。范围 0.00–1.00,精确到百分位。仅 rmbg=1 时可用。 |
shape_base | int | 否 | 底座形状,默认 0。仅 rmbg=0 时可用。0:square(方形)1:circle(圆形) |
thickness_base | string | 否 | 底座厚度,默认 1.0 mm。范围 0.1–20.0 mm,精确到十分位。仅 rmbg=0 时可用。 |
width | int | 否 | 成品宽度,默认 40 mm。范围 20–600 mm。 |
sculpmode | int | 否 | 雕刻模式,默认 0。0:emboss1:engrave |
response_format | string | 否 | 返回结果格式,默认 url。 |
format | int | 是 | 深度图输出格式。1:exr2:png3:stl4:glb5:3mf6:bmp7:obj注意:浮雕的 6 表示 bmp,通用图生 3D 的 6 表示 3mf。 |
响应体
| Field | Type | 说明 |
|---|---|---|
code | int | 响应码,按本端点定义 |
data.task_id | string | 任务ID |
msg | string | 具体消息 |
在控制台配置 Webhook 可接收任务通知,也可使用查询接口轮询。
请求示例
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())响应示例
json
{
"code": 200,
"data": {
"task_id": "<TASK_ID>"
},
"msg": "success"
}错误码
| code | 错误消息 | 说明 |
|---|---|---|
| 5001001 | generate failed | 生成超时或输入解析失败,所耗积分已退还。先检查原任务和输入,再决定是否创建新任务。 |
服务流程 → · Webhook说明 → · 查看积分计费 →
技术支持:apicontact@hi3d.ai
查询任务
提交后保存 task_id,按查询任务中的「图生浮雕」路径读取结果。
技术支持:apicontact@hi3d.ai