Hi3D-comfyUI

ComfyUI custom node package for Hi3D Image-to-3D API. Generate high-quality 3D models from images using Hi3D AI services.

Features

• Image to 3D — Generate 3D models (GLB) from a single image or multi-view images.
• Unified scene switch — Use the scene parameter to switch between general object models and portrait/scene models in one node.
• Model-resolution linkage — The node UI automatically filters available model versions and resolutions based on the selected scene and model.
• Texture regeneration — Re-texture existing 3D models based on a reference image.
• Load 3D model — Load a GLB file from disk with a built-in upload button (GLB only).

Installation

Download from Hi3D Website

1. Download the Hi3D-comfyUI archive from the Hi3D website or the project releases page.
2. Extract it into the ComfyUI/custom_nodes directory.
3. Install Python dependencies via the ComfyUI built-in terminal (click the terminal icon in the ComfyUI Manager toolbar) or any terminal with the same Python environment:

cd ComfyUI/custom_nodes/Hi3D-comfyUI
pip install -r requirements.txt

ComfyUI Manager

Search for Hi3D in ComfyUI Manager and install it directly.

Configuration

An API key pair (ak / sk) is required. Register at the Hi3D website to obtain one.

Option 1: config.json (Recommended)

Edit config.json in the node directory:

{
    "Hi3D_ak": "your_access_key",
    "Hi3D_sk": "your_secret_key"
}

Option 2: Environment Variables

export Hi3D_ak=your_access_key
export Hi3D_sk=your_secret_key

If ak/sk are configured via config.json or environment variables, the input fields on the nodes can be left empty.

Nodes

Hi3D:ImageTo3D

Generates a 3D model (GLB) from a single image or multi-view images.

| Parameter | Type | Description | |-----------|------|-------------| | ak | STRING | API Access Key (leave empty if configured globally) | | sk | STRING | API Secret Key (leave empty if configured globally) | | image | IMAGE | Main front image (required) | | image_back | IMAGE | Back reference image (optional, for multi-view) | | image_left | IMAGE | Left reference image (optional, for multi-view) | | image_right | IMAGE | Right reference image (optional, for multi-view) | | texture | BOOLEAN | Generate texture maps (default: False) | | pbr | BOOLEAN | PBR 开关（默认开启）。关闭=关闭，开启=开启。PBR需要 texture=True，且仅支持 hitem3dv2.0 / hitem3dv2.1。 | | scene | COMBO | Scene preset: general / portrait | | model | COMBO | Model version (filtered by scene, see table below) | | resolution | COMBO | Generation resolution (filtered by model, default: 1024, i.e. 1024³) | | face | INT | Target poly count (100,000–2,000,000, supports custom value). UI recommends by resolution: 512→500000, 1024→1000000, 1536/1536fast/1536pro/1536profast→2000000. |

Scene → Model mapping:

| Scene | Available Models | |-------|-----------------| | general | hitem3dv1.5, hitem3dv2.0, hitem3dv2.1 | | portrait | scene-portraitv1.5, scene-portraitv2.0, scene-portraitv2.1 |

Model → Resolution mapping:

| Model | Available Resolutions | |-------|----------------------| | hitem3dv1.5 | 512, 1024, 1536, 1536pro | | hitem3dv2.0 | 512, 1024, 1536, 1536pro | | hitem3dv2.1 | 1536fast, 1536pro | | scene-portraitv1.5 | 1536 | | scene-portraitv2.0 | 1536pro | | scene-portraitv2.1 | 1536profast, 1536pro |

Outputs:

| Output | Type | Description | |--------|------|-------------| | GLB | FILE3DGLB | Downloaded 3D model in GLB format | | model_task | HI3D_MODEL_TASK | Task info, can be passed to the Texture node |

---

Hi3D:Texture

Regenerates texture maps for an existing 3D model based on a reference image.

| Parameter | Type | Description | |-----------|------|-------------| | ak | STRING | API Access Key (leave empty if configured globally) | | sk | STRING | API Secret Key (leave empty if configured globally) | | GLB | FILE3DGLB | Input 3D model in GLB format | | image | IMAGE | Texture reference image (required) | | model_task | HI3D_MODEL_TASK | Upstream task info from ImageTo3D (optional) | | model | COMBO | Model version: hitem3dv1.5 / hitem3dv2.0 / hitem3dv2.1 / scene-portraitv1.5 | | pbr | BOOLEAN | PBR 开关（默认开启）。关闭=关闭，开启=开启。仅支持 hitem3dv2.0 / hitem3dv2.1。 |

Provide either model_task or GLB. When model_task is connected, its model URL is used automatically without re-uploading.

Outputs: Same as ImageTo3D.

---

Hi3D:Load3DModel

Loads a GLB file from disk for use with the Texture node. Includes an Upload GLB File button to browse and upload files from your local computer.

| Parameter | Type | Description | |-----------|------|-------------| | model_file | COMBO | Select a GLB file from the dropdown or upload a new one |

Output:

| Output | Type | Description | |--------|------|-------------| | model_3d | FILE3D | Loaded 3D model, can be connected to the Texture node's GLB input |

Example Workflows

Image to 3D

Generate a 3D model from a single image:

Texture Regeneration

Re-texture an existing 3D model with a reference image:

License

MIT