Image to 3D
Generate 3D geometry, with optional textures, from one image or multiple views. To add textures to existing geometry, see Texturing.
Submit a generation task and use its task ID to query the result. Each endpoint defines its own authentication and parameters.
Create task
POST https://api.hitem3d.ai/open-api/v1/submit-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 |
|---|---|---|---|
request_type | int | Yes | Generation mode. Defaults to 3 (geometry and texture).1 (mesh): generate geometry only.2 (texture): generate texture for existing geometry.3 (both): generate geometry and texture in one task. |
model | String | Yes | Model version. Defaults to hi3dv3.0.General: hitem3dv1.5, hitem3dv2.0, hitem3dv2.1, hi3dv3.0.Portrait: scene-portraitv1.5, scene-portraitv2.0, scene-portraitv2.1. |
images | file | Yes, choose either this or multi_images | Upload one image as a form file for single-image generation. Supported formats: png, jpeg, jpg, webp. Limit: 20 MB. |
multi_images | file | Yes, choose either this or images | Upload 2–4 images as form files. Include the front view. Submit images in front, back, left, right order. Use the same formats as images, up to 20 MB per image. |
multi_images_bit | string | No | Four positions used with multi_images, in front, back, left, right order. 1 means an image is present and 0 means absent.For example, 1010 selects front and left. The number of 1s must match the number of uploaded images. |
resolution | string | No | Output resolution. hi3dv3.0 defaults to 2048quality.General models v1.5: 512, 1024, 1536, 1536prov2.0: 1536, 1536prov2.1: 1536fast, 1536prov3.0: 2048quality, 2048masterPortrait models v1.5: 1536v2.0: 1536prov2.1: 1536profast, 1536pro |
mesh_url | string | No | Only used when request_type=2. Supply either this field or mesh.URL of an existing geometry model in GLB format. |
mesh | file | No | Only used when request_type=2. Supply either this field or mesh_url.Upload an existing geometry model in GLB format. |
pbr | int | No | Only used when request_type is 2 or 3. Supported by v2.0, v2.1 and v3.0 models only.Default: 1.1: On0: Off |
rmbg | int | No | Input image background removal. Default: 1.1: On0: Off |
shading | BigDecimal | No | De-lighting strength. Defaults to 0.5. Range: 0.0–1.0 in tenths.Supported by v2.0, v2.1 and v3.0 models only. |
face | int | No | Model face count. Range: 100000–5000000.Recommended counts by resolution 512: 5000001024: 10000001536, 1536fast, 1536pro, 2048quality: 20000002048master: 5000000 |
format | int | No | One output format per task. Default: 1 (obj).1: obj2: glb3: stl4: fbx5: usdz6: 3mf |
Response body
| Field | Type | Description |
|---|---|---|
code | int | Response code. |
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
Choose request_type for the output you want, then pick a single-image or multi-view example. Multi-view examples use front and left images (multi_images_bit=1010).
Geometry and texture (default) · request_type=3
Single image
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'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())Multi-view
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'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())Geometry only · request_type=1
Single image
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'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())Multi-view
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'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())Texturing · request_type=2
Provide reference images and an existing GLB.
Single image
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"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())Multi-view
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"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())Response example
{
"code": 200,
"data": {
"task_id": "<TASK_ID>"
},
"msg": "success"
}Error codes
| code | Message | Description |
|---|---|---|
| 30010000 | balance is not enough | Insufficient credit balance |
| 10031001 | Upload file size exceeds limit | Uploaded file exceeds 20 MB |
| 10031002 | Face not valid | Invalid face count. Check the face range and recommended values in the request body. |
| 10031003 | Resolution not valid | Resolution is not supported by the model |
| 10031004 | request type not support | Unsupported request type |
| 10031005 | images only allow png jpeg jpg webp | Unsupported image format |
| 10031006 | model not valid | Unsupported model identifier |
| 10031007 | both images and multi images provided | Single-image and multi-view inputs cannot both be provided |
| 10031008 | images or multi images required | Provide a single-image or multi-view input |
| 10031009 | multi images count exceeds limit | At most four multi-view images |
| 10031010 | empty file not allowed | Empty file; check form upload encoding |
| 10031011 | mesh url or mesh required when request type 2 | Texture generation requires mesh_url or mesh |
| 10031012 | mesh_url_must_start_with_http | mesh_url must start with http |
| 10031013 | multi images bit length error | multi_images_bit must contain four positions |
| 10031014 | multi images bit invalid char error | multi_images_bit accepts only 0/1 |
| 10031015 | multi_images_bit_count_mismatch_error | The number of 1s must match the image count |
| 10031016 | mesh format not supported | mesh and mesh_url support only GLB |
| 10031017 | model does not support texture | The requested model does not support texturing (request_type=2). |
| 10000000 | system error | Internal system error |
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 3D route in Query task.
API support:apicontact@hi3d.ai