图生3D
从单图或多视图生成 3D 几何,或同时生成几何与纹理。基于已有模型生成纹理见贴图。
提交生成任务并使用任务 ID 查询结果。每个端点的鉴权与参数分别定义。
创建任务
POST https://api.hitem3d.ai/open-api/v1/submit-task
请求头
| Header | 值 |
|---|---|
Authorization | Bearer <accessToken>。令牌取自获取 Token接口返回的 data.accessToken。 |
| Content-Type | multipart/form-data(文件上传时由客户端生成boundary) |
请求体
| 参数 | 类型 | 必填 | 参数描述 |
|---|---|---|---|
request_type | int | 是 | 生成方式,默认 3(几何 + 纹理)。1(mesh):仅生成几何。2(texture):在已有几何模型上生成纹理。3(both):一次生成几何和纹理。 |
model | String | 是 | 模型版本,默认 hi3dv3.0。通用模型: hitem3dv1.5、hitem3dv2.0、hitem3dv2.1、hi3dv3.0。肖像模型: scene-portraitv1.5、scene-portraitv2.0、scene-portraitv2.1。 |
images | file | 是,与 multi_images 二选一 | 通过表单上传 1 张图片,用于单图生成。 支持 png、jpeg、jpg、webp,不超过 20 MB。 |
multi_images | file | 是,与 images 二选一 | 通过表单上传 2–4 张图片,必须包含前视图。 按前、后、左、右的顺序提交,每张不超过 20 MB,格式同 images。 |
multi_images_bit | string | 否 | 与 multi_images 配合使用。4 位分别对应前、后、左、右视图,1 表示该视图有图片,0 表示无图片。例如 1010 表示提交前视图和左视图。1 的数量须与上传图片数一致。 |
resolution | string | 否 | 输出分辨率。hi3dv3.0 默认 2048quality。通用模型 v1.5: 512、1024、1536、1536prov2.0: 1536、1536prov2.1: 1536fast、1536prov3.0: 2048quality、2048master肖像模型 v1.5: 1536v2.0: 1536prov2.1: 1536profast、1536pro |
mesh_url | string | 否 | 仅 request_type=2 时可使用。 与 mesh 二选一。填写已有几何模型的 URL,仅支持 GLB。 |
mesh | file | 否 | 仅 request_type=2 时可使用。 与 mesh_url 二选一。上传已有几何模型文件,仅支持 GLB。 |
pbr | int | 否 | 仅 request_type 为 2 或 3 时可使用。 仅 v2.0、v2.1、v3.0 模型支持。默认 1。1:开启0:关闭 |
rmbg | int | 否 | 输入图片去背景开关,默认 1。1:开启0:关闭 |
shading | BigDecimal | 否 | 去光影程度,默认 0.5。范围 0.0–1.0,精确到十分位。仅 v2.0、v2.1、v3.0 模型支持。 |
face | int | 否 | 模型面数,范围 100000–5000000。各分辨率的推荐值 512:5000001024:10000001536、1536fast、1536pro、2048quality:20000002048master:5000000 |
format | int | 否 | 每次生成一种格式,默认 1(obj)。1:obj2:glb3:stl4:fbx5:usdz6:3mf |
响应体
| Field | Type | 说明 |
|---|---|---|
code | int | 接口响应码。 |
data.task_id | String | 任务ID |
msg | String | 具体消息 |
在控制台配置 Webhook 可接收任务通知,也可使用查询接口轮询。
请求示例
先按生成目标选择 request_type,再选单图或多视图。多视图示例均使用前视图和左视图(multi_images_bit=1010)。
几何 + 纹理(默认) · request_type=3
单图
bash
curl --request POST 'https://api.hitem3d.ai/open-api/v1/submit-task' \
--header "Authorization: Bearer $HI3D_TOKEN" \
--form 'images=@./input.png' \
--form 'request_type=3' \
--form 'model=hi3dv3.0' \
--form 'resolution=2048quality' \
--form 'format=2' \
--form 'pbr=1'python
import os
import requests
data = {
"request_type": "3",
"model": "hi3dv3.0",
"resolution": "2048quality",
"format": "2",
"pbr": "1",
}
with open("input.png", "rb") as file_0:
files = [
("images", ("input.png", file_0)),
]
response = requests.post(
"https://api.hitem3d.ai/open-api/v1/submit-task",
headers={"Authorization": "Bearer " + os.environ["HI3D_TOKEN"]},
data=data,
files=files,
)
response.raise_for_status()
print(response.json())多视图
bash
curl --request POST 'https://api.hitem3d.ai/open-api/v1/submit-task' \
--header "Authorization: Bearer $HI3D_TOKEN" \
--form 'multi_images=@./front.png' \
--form 'multi_images=@./left.png' \
--form 'request_type=3' \
--form 'model=hi3dv3.0' \
--form 'resolution=2048quality' \
--form 'format=2' \
--form 'pbr=1' \
--form 'multi_images_bit=1010'python
import os
import requests
data = {
"request_type": "3",
"model": "hi3dv3.0",
"resolution": "2048quality",
"format": "2",
"pbr": "1",
"multi_images_bit": "1010",
}
with open("front.png", "rb") as file_0, open("left.png", "rb") as file_1:
files = [
("multi_images", ("front.png", file_0)),
("multi_images", ("left.png", file_1)),
]
response = requests.post(
"https://api.hitem3d.ai/open-api/v1/submit-task",
headers={"Authorization": "Bearer " + os.environ["HI3D_TOKEN"]},
data=data,
files=files,
)
response.raise_for_status()
print(response.json())仅几何 · request_type=1
单图
bash
curl --request POST 'https://api.hitem3d.ai/open-api/v1/submit-task' \
--header "Authorization: Bearer $HI3D_TOKEN" \
--form 'images=@./input.png' \
--form 'request_type=1' \
--form 'model=hi3dv3.0' \
--form 'resolution=2048quality' \
--form 'format=2'python
import os
import requests
data = {
"request_type": "1",
"model": "hi3dv3.0",
"resolution": "2048quality",
"format": "2",
}
with open("input.png", "rb") as file_0:
files = [
("images", ("input.png", file_0)),
]
response = requests.post(
"https://api.hitem3d.ai/open-api/v1/submit-task",
headers={"Authorization": "Bearer " + os.environ["HI3D_TOKEN"]},
data=data,
files=files,
)
response.raise_for_status()
print(response.json())多视图
bash
curl --request POST 'https://api.hitem3d.ai/open-api/v1/submit-task' \
--header "Authorization: Bearer $HI3D_TOKEN" \
--form 'multi_images=@./front.png' \
--form 'multi_images=@./left.png' \
--form 'request_type=1' \
--form 'model=hi3dv3.0' \
--form 'resolution=2048quality' \
--form 'format=2' \
--form 'multi_images_bit=1010'python
import os
import requests
data = {
"request_type": "1",
"model": "hi3dv3.0",
"resolution": "2048quality",
"format": "2",
"multi_images_bit": "1010",
}
with open("front.png", "rb") as file_0, open("left.png", "rb") as file_1:
files = [
("multi_images", ("front.png", file_0)),
("multi_images", ("left.png", file_1)),
]
response = requests.post(
"https://api.hitem3d.ai/open-api/v1/submit-task",
headers={"Authorization": "Bearer " + os.environ["HI3D_TOKEN"]},
data=data,
files=files,
)
response.raise_for_status()
print(response.json())贴图 · request_type=2
提交参考图和已有 GLB。
单图
bash
curl --request POST 'https://api.hitem3d.ai/open-api/v1/submit-task' \
--header "Authorization: Bearer $HI3D_TOKEN" \
--form 'images=@./input.png' \
--form 'request_type=2' \
--form 'model=hi3dv3.0' \
--form 'resolution=2048quality' \
--form 'format=2' \
--form 'pbr=1' \
--form "mesh_url=$HI3D_MESH_URL"python
import os
import requests
data = {
"request_type": "2",
"model": "hi3dv3.0",
"resolution": "2048quality",
"format": "2",
"pbr": "1",
"mesh_url": os.environ["HI3D_MESH_URL"],
}
with open("input.png", "rb") as file_0:
files = [
("images", ("input.png", file_0)),
]
response = requests.post(
"https://api.hitem3d.ai/open-api/v1/submit-task",
headers={"Authorization": "Bearer " + os.environ["HI3D_TOKEN"]},
data=data,
files=files,
)
response.raise_for_status()
print(response.json())多视图
bash
curl --request POST 'https://api.hitem3d.ai/open-api/v1/submit-task' \
--header "Authorization: Bearer $HI3D_TOKEN" \
--form 'multi_images=@./front.png' \
--form 'multi_images=@./left.png' \
--form 'request_type=2' \
--form 'model=hi3dv3.0' \
--form 'resolution=2048quality' \
--form 'format=2' \
--form 'pbr=1' \
--form 'multi_images_bit=1010' \
--form "mesh_url=$HI3D_MESH_URL"python
import os
import requests
data = {
"request_type": "2",
"model": "hi3dv3.0",
"resolution": "2048quality",
"format": "2",
"pbr": "1",
"multi_images_bit": "1010",
"mesh_url": os.environ["HI3D_MESH_URL"],
}
with open("front.png", "rb") as file_0, open("left.png", "rb") as file_1:
files = [
("multi_images", ("front.png", file_0)),
("multi_images", ("left.png", file_1)),
]
response = requests.post(
"https://api.hitem3d.ai/open-api/v1/submit-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 | 错误消息 | 说明 |
|---|---|---|
| 30010000 | balance is not enough | 积分余额不足 |
| 10031001 | Upload file size exceeds limit | 上传文件超过20 MB |
| 10031002 | Face not valid | 面数无效。按请求体核对 face 的范围和推荐值。 |
| 10031003 | Resolution not valid | 分辨率不属于该模型支持范围 |
| 10031004 | request type not support | 请求类型不支持 |
| 10031005 | images only allow png jpeg jpg webp | 图片格式不支持 |
| 10031006 | model not valid | 模型标识不支持 |
| 10031007 | both images and multi images provided | 单图和多视图不能同时上传 |
| 10031008 | images or multi images required | 须提供单图或多视图 |
| 10031009 | multi images count exceeds limit | 多视图最多4张 |
| 10031010 | empty file not allowed | 文件不能为空,核对表单上传方式 |
| 10031011 | mesh url or mesh required when request type 2 | 纹理生成须提供mesh_url或mesh |
| 10031012 | mesh_url_must_start_with_http | mesh_url须以http开头 |
| 10031013 | multi images bit length error | multi_images_bit长度须为4 |
| 10031014 | multi images bit invalid char error | multi_images_bit只能包含0/1 |
| 10031015 | multi_images_bit_count_mismatch_error | 位图中1的数量须与图片数相同 |
| 10031016 | mesh format not supported | mesh与mesh_url仅支持GLB |
| 10031017 | model does not support texture | 当前请求的模型不支持贴图(request_type=2)。 |
| 10000000 | system error | 系统内部异常 |
服务流程 → · Webhook说明 → · 查看积分计费 →
技术支持:apicontact@hi3d.ai
查询任务
提交后保存 task_id,按查询任务中的「图生3D」路径读取结果。
技术支持:apicontact@hi3d.ai