The China and Global distributions use different API keys, endpoints, and region settings; do not mix their configuration. Install only one regional distribution per agent or workspace unless the environments are isolated.

Industry Applications

From gaming to e-commerce, Lux3D powers the next generation of 3D content creation.

E-Commerce

Create 3D product visualizations for immersive shopping experiences.

Product configurators
AR Try-On
Virtual Showrooms

<table width="100%"> <tr> <th align="center" width="50%">Input Image</th> <th align="center" width="50%">Generated Result</th> </tr> <tr> <td align="center" width="50%"> <img src="figures/handbag.jpg" height="200" alt="Input"> </td> <td align="center" width="50%"> <img src="figures/handbag.gif" height="200" alt="Output"> </td> </tr> <tr> <td align="center" width="50%"> <img src="figures/chips.jpg" height="200" alt="Input"> </td> <td align="center" width="50%"> <img src="figures/chips.gif" height="200" alt="Output"> </td> </tr> <tr> <td align="center" width="50%"> <img src="figures/milk-carton.jpg" height="200" alt="Input"> </td> <td align="center" width="50%"> <img src="figures/milk-carton-render.png" height="200" alt="Output"> </td> </tr> <tr> <td align="center" width="50%"> <img src="figures/Lawnmower.jpg" height="200" alt="Input"> </td> <td align="center" width="50%"> <img src="figures/Lawnmower-output.jpg" height="200" alt="Output"> </td> </tr> <tr> <td align="center" width="50%"> <img src="figures/Pet-bowl.png" height="200" alt="Input"> </td> <td align="center" width="50%"> <img src="figures/Pet-bowl-output.jpg" height="200" alt="Output"> </td> </tr> <tr> <td align="center" width="50%"> <img src="figures/Speaker.png" height="200" alt="Input"> </td> <td align="center" width="50%"> <img src="figures/Speaker-output.jpg" height="200" alt="Output"> </td> </tr> <tr> <td align="center" width="50%"> <img src="figures/vase.jpg" height="200" alt="Input"> </td> <td align="center" width="50%"> <img src="figures/vase-output.jpg" height="200" alt="Output"> </td> </tr> </table>

Game Development

Rapidly prototype and generate assets for your game worlds.

Props & Environment
Character Accessories
Level Design

Industrial Design

Visualize concepts and prototypes with speed and precision.

Concept Visualization
Digital Twins
Rapid Prototyping

<table width="100%"> <tr> <th align="center" width="50%">Input Images</th> <th align="center" width="50%">Generated Result</th> </tr> <tr> <td align="center" width="50%"> <img src="figures/industrial1.jpg" height="180" alt="Input 1"> <img src="figures/industrial2.jpg" height="180" alt="Input 2"> <img src="figures/industrial3.jpg" height="180" alt="Input 3"> </td> <td align="center" width="50%"> <video src="https://github.com/user-attachments/assets/67ed25c7-a843-4484-a509-fbc53fc11630" controls width="100%"></video> </td> </tr> </table>

Furniture & Interior

Rapidly digitize furniture and create realistic 3D assets for interior planning.

Furniture Digitization
Room Planning
Virtual Staging

<table width="100%"> <tr> <th align="center" width="50%">Input Image</th> <th align="center" width="50%">Generated Result</th> </tr> <tr> <td align="center" width="50%"> <img src="figures/leather-sofa.png" height="200" alt="Input"> </td> <td align="center" width="50%"> <img src="figures/leather-sofa.gif" height="200" alt="Output"> </td> </tr> <tr> <td align="center" width="50%"> <img src="figures/marble-coffee-table.png" height="200" alt="Input"> </td> <td align="center" width="50%"> <img src="figures/marble-coffee-table.gif" height="200" alt="Output"> </td> </tr> <tr> <td align="center" width="50%"> <img src="figures/refrigerator.jpg" height="200" alt="Input"> </td> <td align="center" width="50%"> <img src="figures/refrigerator-render.png" height="200" alt="Output"> </td> </tr> <tr> <td align="center" width="50%"> <img src="figures/stainless-steel-table.png" height="200" alt="Input"> </td> <td align="center" width="50%"> <img src="figures/stainless-steel-table-render.png" height="200" alt="Output"> </td> </tr> <tr> <td align="center" width="50%"> <img src="figures/furniture.png" height="200" alt="Input"> </td> <td align="center" width="50%"> <video src="https://github.com/user-attachments/assets/3ca88eb5-5cc3-4952-aedd-74ab8df1fede" controls width="100%"></video> </td> </tr> <tr> <td align="center" width="50%"> <img src="figures/Office-chair.jpg" height="200" alt="Input"> </td> <td align="center" width="50%"> <video src="https://github.com/user-attachments/assets/7536eb17-c717-4291-b59e-e21d886096a8" controls width="100%"></video> </td> </tr> <tr> <td align="center" width="50%"> <img src="figures/Outdoor-furniture.jpg" height="200" alt="Input"> </td> <td align="center" width="50%"> <img src="figures/Outdoor-furniture-output.jpg" height="200" alt="Output"> </td> </tr> </table>

Features

Lux3D Image to 3D

Provides 1–8 image slots; each accepts a public HTTP(S) URL, an upstream STRING URL, or one connected ComfyUI IMAGE
Uploads local IMAGE inputs through Asset/OUS before task submission
Supports G1 / G1-Turbo, target face count, ZIP / GLB / PLY output, PBR, and size prediction
Polls automatically for up to about 15 minutes
Returns separate task_id, lux3d_zip, glb, and ply outputs

Lux3D Text to 3D

Converts a text description into a 3D model
Accepts an optional public image URL, upstream STRING URL, or one ComfyUI IMAGE as a reference
Multiple styles: photorealistic, cartoon, anime, hand-painted, cyberpunk, fantasy, glass
Shares the version, face-count, output-format, PBR, and size-prediction controls of Image to 3D
Returns separate task_id, lux3d_zip, glb, and ply outputs

Lux3D Multi-View Generator

Accepts an optional public image URL, upstream STRING URL, or ComfyUI IMAGE, plus an optional text prompt; at least one is required
Supports image-only, text-only, and image-plus-text generation
Returns task_id plus image_1 through image_4 in FRONT_THREE_QUARTER, OPPOSITE_THREE_QUARTER, SIDE, and BACK order

Lux3D Single Image Generator

Generates one new image from an optional public image URL, upstream STRING URL, or ComfyUI IMAGE, plus an optional multiline prompt; at least one is required
Supports image-only, text-only, and image-plus-text generation; image-only input is regenerated rather than passed through
Creates and polls the task internally, then returns task_id and image_url

Lux3D Multi-Format Export

Exports a remote or ComfyUI-local .glb / .zip model to any combination of USDZ, OBJ ZIP, FBX ZIP, STL, and 3MF
Uploads local models through Asset/OUS before task submission
Maps the service's fixed result slots by position instead of guessing formats from filenames
Uses the backward-compatible output order task_id, glb, usdz, obj_zip, fbx_zip, stl, 3mf, and lux3d_zip

Lux3D Material Redraw

Redraws an existing GLB from a public image URL, upstream STRING URL, or one ComfyUI IMAGE
Accepts a public GLB URL, upstream STRING URL, or ComfyUI-local GLB through mesh_url
Creates and polls a material-redraw task, then returns a new glb_model_url

Lux3D Viewer

Previews remote or local GLB and PLY Gaussian-splat files in the ComfyUI canvas
Loads local models through ComfyUI's /view route without uploading them to Lux3D
Returns the resolved model_url for downstream nodes

Installation

ComfyUI CLI (recommended)

comfy node install lux3d

ComfyUI Manager

Open ComfyUI.
Go to Manager → Custom Nodes.
Click "Install via URL".
Enter: https://github.com/manycore-research/ComfyUI-Lux3D.git

Manual Installation

Clone this repository into ComfyUI's custom_nodes directory:

cd path/to/ComfyUI/custom_nodes
git clone [email protected]:manycore-research/ComfyUI-Lux3D.git

Install dependencies if needed:
```
pip install -r requirements.txt
```
Configure the API key in the server environment that starts ComfyUI. Set LUX3D_API_KEY_CN for the China service or LUX3D_API_KEY_INTL for the international service. If you use only one region, set only its variable.
Restart ComfyUI.

🚀 Want a quick preview first? Try the official site: Lux3D China | Lux3D Global

Usage

Getting an API key

China service: https://labs.aholo3d.cn/api-keys
International service: https://labs.aholo3d.com/api-keys

If you have any questions, contact us at [email protected].

Recommended Basic Workflows

The current release provides seven nodes, which can be combined as needed.

Lux3D Image to 3D

Find Lux3D Image to 3D under Lux3D/Generate, or double-click an empty area to search and add it.
Provide at least one source in image_1 through image_8. Each slot accepts a public HTTP(S) URL, an upstream STRING URL, or one IMAGE, and the source types may be mixed.
Select base_api_path, the generation version, face count, and required output formats, then run the workflow.
After polling completes, the node returns task_id, lux3d_zip, glb, and ply. A format that was not requested or returned is an empty string.
Connect a non-empty glb or ply output to Lux3D Viewer for in-canvas preview. ZIP output cannot be previewed directly.

Lux3D Text to 3D

Find Lux3D Text to 3D under Lux3D/Generate.
Enter a text prompt describing the object.
Optionally enter a public HTTP(S) URL in reference_image, connect an upstream STRING URL, or connect one reference IMAGE.
Choose a style from the dropdown:
- photorealistic: Photorealistic (default)
- cartoon: Cartoon
- anime: Anime
- hand_painted: Hand-painted
- cyberpunk: Cyberpunk
- fantasy: Fantasy
- glass: Glass
Select base_api_path, the generation version, face count, and required output formats, then run the workflow.
After polling completes, the node returns task_id, lux3d_zip, glb, and ply.
Connect a non-empty glb or ply output to Lux3D Viewer for in-canvas preview.

Lux3D Multi-View Generator

Add Lux3D Multi-View Generator from Lux3D/Generate.
Optionally enter a public HTTP(S) URL in image, connect an upstream STRING URL, or connect one IMAGE. Optionally enter a multiline prompt. At least one of image and prompt is required, so the node supports image-only, text-only, and image-plus-text generation.
Select base_api_path and run the workflow. The node returns task_id and four image URLs in a stable order: image_1 = FRONT_THREE_QUARTER, image_2 = OPPOSITE_THREE_QUARTER, image_3 = SIDE, and image_4 = BACK.

Lux3D Single Image Generator

Add Lux3D Single Image Generator from Lux3D/Generate.
Optionally enter a public HTTP(S) URL in image, connect an upstream STRING URL, or connect one IMAGE. Optionally enter a multiline prompt. At least one of image and prompt is required.
Select base_api_path and run the workflow. The node creates and polls the task internally, then returns task_id and image_url. Image-only input still produces a newly generated image; the source URL is not passed through as the result.

Lux3D Multi-Format Export

Add Lux3D Multi-Format Export from Lux3D/Export.
Enter a public .glb / .zip URL in model_url, connect an upstream STRING URL, or use the node's button to select a ComfyUI-local model.
Select the export formats. A GLB input requires at least one explicit format; a ZIP input may use default.
Run the workflow. The node returns task_id, glb, usdz, obj_zip, fbx_zip, stl, 3mf, and lux3d_zip, in that order. The first five sockets retain their historical positions; unrequested or unavailable results are empty strings.
For a ZIP input, lux3d_zip returns the source Lux3D ZIP and glb returns the default GLB export. For a GLB input, glb returns the original model URL and lux3d_zip is empty.

Lux3D Material Redraw

Find the Lux3D Material Redraw node under the Lux3D category in the ComfyUI node library.
Enter a public HTTP(S) URL in image, connect an upstream STRING URL, or connect one material-reference IMAGE.
Enter a public GLB URL in mesh_url, connect an upstream STRING URL, or use the node's button to select a ComfyUI-local GLB.
Run the workflow. The node returns a new glb_model_url with the redrawn material.
The returned model URL can be connected to the Lux3D Viewer node for in-canvas preview.

Lux3D Viewer

Add Lux3D Viewer from the Lux3D category.
Connect an upstream glb / ply URL to model_url, enter a public URL manually, or use the node's button to select a ComfyUI-local .glb / .ply file.
Run the workflow to preview the model in the canvas and return the resolved model_url. Local models are never uploaded to Lux3D.

Node Reference

The current release registers seven nodes. Generation, export, and material-redraw nodes create asynchronous tasks internally and poll until completion, with up to 60 checks at 15-second intervals (about 15 minutes).

Common conventions:

base_api_path accepts https://api.aholo3d.cn (China) or https://api.aholo3d.com (international). Do not add a trailing slash.
Nodes other than Lux3D Viewer no longer expose an API-key input. Set LUX3D_API_KEY_CN or LUX3D_API_KEY_INTL in the ComfyUI server environment to match base_api_path.
Image fields typed as STRING / IMAGE accept a public HTTP(S) URL, an upstream STRING URL, or a connected ComfyUI IMAGE containing exactly one image. Local images are uploaded through Asset/OUS before the Lux3D task is submitted; nodes use the resulting asset URL and do not expose Base64 data URLs.
Model fields with local-file support provide a picker for the ComfyUI input directory and also accept relative files from output or temp (marked with [output] or [temp]). Local models used by Lux3D tasks are uploaded first.
The multi-format service returns seven fixed slots in zipUrl, glbUrl, usdzUrl, objZipUrl, fbxZipUrl, stlUrl, threeMfUrl order. The plugin maps these slots by position rather than inferring formats from filenames; a format that was not requested or returned is represented by an empty string.

Lux3D Viewer

Category: Lux3D

Previews a GLB model or PLY Gaussian-splat file in the ComfyUI canvas. Remote URLs pass through unchanged. Local files are not uploaded; they are converted to a same-origin ComfyUI /view URL.

GLB preview uses the same model-viewer 4.2.0 runtime and preset as the Web GLB Viewer: black background, the same HDR environment, exposure 0.95, auto tone mapping, a 30° field of view, and a 125% initial camera distance. Shadows and auto-rotation are disabled; orbit, zoom, pan, and model animation remain enabled. Runtime, HDR, and decoders are bundled locally. Restart ComfyUI and refresh the browser after updating the plugin's viewer assets.

Inputs

| Input | Type | Description | | --- | --- | --- | | model_url | STRING / model source | Public HTTP(S) .glb / .ply URL, upstream STRING output, or a local .glb / .ply file in ComfyUI input, output, or temp | | base_api_path | STRING | Validates the region endpoint and accepts only the two supported API URLs; previewing does not call the Lux3D API |

Outputs

| Output | Type | Description | | --- | --- | --- | | model_url | STRING | Resolved model URL for downstream nodes; remote input is unchanged and local input becomes a ComfyUI /view URL |

Lux3D Image to 3D

Category: Lux3D/Generate

Creates an image-to-3D task from 1–8 images. Public URLs, upstream STRING URLs, and local IMAGE inputs can be mixed across the slots.

Inputs

| Input | Type | Description | | --- | --- | --- | | base_api_path | STRING | Lux3D API endpoint: https://api.aholo3d.cn (China) or https://api.aholo3d.com (international) | | image_1 … image_8 | STRING / IMAGE | Each slot may be empty, a public HTTP(S) image URL, an upstream STRING URL, or one connected IMAGE; at least one of the eight slots is required | | version | Enum | G1 / G1-Turbo; defaults to G1-Turbo | | face_count | INT | Target face count; defaults to 200000. 0 omits the field; a nonzero value must be 10000–300000 | | output_format | Enum | default, zip, glb, ply, zip,glb, zip,ply, glb,ply, or zip,glb,ply; default omits the field. G1 always returns ZIP + GLB and can additionally return PLY; G1-Turbo follows the selected combination | | enable_pbr | Enum | default / true / false; supported only by G1-Turbo and not applicable to a PLY-only request | | ai_predict_size | Enum | default / true / false; enables size prediction |

Outputs

| Output | Type | Description | | --- | --- | --- | | task_id | STRING | Lux3D task ID | | lux3d_zip | STRING | Lux3D ZIP result URL | | glb | STRING | GLB model URL | | ply | STRING | PLY Gaussian-splat result URL |

Lux3D Text to 3D

Category: Lux3D/Generate

Creates a text-to-3D task from a prompt and one optional reference image.

Inputs

| Input | Type | Description | | --- | --- | --- | | base_api_path | STRING | Lux3D API endpoint: https://api.aholo3d.cn (China) or https://api.aholo3d.com (international) | | prompt | STRING | Non-empty text describing the object to generate | | style | Enum | photorealistic (default), cartoon, anime, hand_painted, cyberpunk, fantasy, or glass | | reference_image | STRING / IMAGE | Optional public HTTP(S) reference-image URL, upstream STRING URL, or one local IMAGE | | version | Enum | G1 / G1-Turbo; defaults to G1-Turbo | | face_count | INT | Target face count; defaults to 200000. 0 omits the field; a nonzero value must be 10000–300000 | | output_format | Enum | The same ZIP / GLB / PLY choices as Lux3D Image to 3D | | enable_pbr | Enum | default / true / false; supported only by G1-Turbo and not applicable to a PLY-only request | | ai_predict_size | Enum | default / true / false; enables size prediction |

Outputs

Lux3D Multi-View Generator

Category: Lux3D/Generate

Generates four multi-view images from an optional object image and/or a text prompt. Image-only, text-only, and image-plus-text requests are supported.

Inputs

| Input | Type | Description | | --- | --- | --- | | base_api_path | STRING | Lux3D API endpoint: https://api.aholo3d.cn (China) or https://api.aholo3d.com (international) | | image | STRING / IMAGE | Optional public HTTP(S) image URL, upstream STRING URL, or one local IMAGE; local input is uploaded through Asset/OUS | | prompt | STRING | Optional multiline generation prompt; at least one of image and prompt is required |

Outputs

| Output | Type | Description | | --- | --- | --- | | task_id | STRING | Lux3D task ID | | image_1 | STRING | FRONT_THREE_QUARTER image URL | | image_2 | STRING | OPPOSITE_THREE_QUARTER image URL | | image_3 | STRING | SIDE image URL | | image_4 | STRING | BACK image URL |

Lux3D Single Image Generator

Registered node key: Lux3DOpenAPISingleImageGenerator

Category: Lux3D/Generate

Generates one new image from an optional image and/or a text prompt. It creates and polls the OpenAPI task internally. Image-only input is regenerated rather than returned unchanged.

Inputs

| Input | Type | Description | | --- | --- | --- | | base_api_path | STRING | Lux3D API endpoint: https://api.aholo3d.cn (China) or https://api.aholo3d.com (international) | | image | STRING / IMAGE | Optional public HTTP(S) image URL, upstream STRING URL, or one local IMAGE; local input is uploaded through Asset/OUS | | prompt | STRING | Optional multiline generation prompt; at least one of image and prompt is required |

Outputs

| Output | Type | Description | | --- | --- | --- | | task_id | STRING | Lux3D task ID | | image_url | STRING | URL of the newly generated image; never a Base64 data URL |

Lux3D Multi-Format Export

Category: Lux3D/Export

Exports a remote or ComfyUI-local GLB / Lux3D ZIP model to one or more target formats. Local files are uploaded to Lux3D first. A ZIP input returns the source ZIP through lux3d_zip and its default GLB export through glb. A GLB input returns the original model URL through glb, requires at least one explicit target format, and leaves lux3d_zip empty.

Inputs

| Input | Type | Description | | --- | --- | --- | | base_api_path | STRING | Lux3D API endpoint: https://api.aholo3d.cn (China) or https://api.aholo3d.com (international) | | model_url | STRING / model source | Public HTTP(S) .glb / .zip URL, upstream STRING output, or a local ComfyUI .glb / .zip file | | output_format | Enum | default; any one of usdz, obj_zip, fbx_zip, stl, or 3mf; or any non-duplicate combination of those five formats. A GLB input requires at least one explicit export format, so default applies only to ZIP input |

Outputs

| Output | Type | Description | | --- | --- | --- | | task_id | STRING | Lux3D task ID | | glb | STRING | Default GLB export for ZIP input; original model URL for GLB input | | usdz | STRING | USDZ file URL | | obj_zip | STRING | OBJ ZIP file URL | | fbx_zip | STRING | FBX ZIP file URL | | stl | STRING | STL file URL | | 3mf | STRING | 3MF file URL | | lux3d_zip | STRING | Source Lux3D ZIP URL for ZIP input; empty for GLB input |

The output socket order is task_id, glb, usdz, obj_zip, fbx_zip, stl, 3mf, lux3d_zip; the first five positions are unchanged for compatibility with existing workflows. The service response itself has seven fixed positions—zipUrl, glbUrl, usdzUrl, objZipUrl, fbxZipUrl, stlUrl, and threeMfUrl—which the plugin maps directly without relying on URL filenames or extensions.

Lux3D Material Redraw

Category: Lux3D

Redraws the material of an existing GLB from one reference image using the fixed v3.0-standard version. A connected local image and a selected local GLB are uploaded before task submission.

Inputs

| Input | Type | Description | | --- | --- | --- | | image | STRING / IMAGE | Required public HTTP(S) reference-image URL, upstream STRING URL, or one local IMAGE | | mesh_url | STRING / model source | Public HTTP(S) .glb URL, upstream STRING output, or a local ComfyUI .glb file | | base_api_path | STRING | Lux3D API endpoint: https://api.aholo3d.cn (China) or https://api.aholo3d.com (international) |

Outputs

| Output | Type | Description | | --- | --- | --- | | glb_model_url | STRING | Download URL for the model with the redrawn material |

FAQ

If the ComfyUI Manager shows a security-level warning when installing this plugin, adjust the corresponding security level in the ComfyUI Manager config and retry.

Development

Project Structure

comfyui-lux3d/
├── __init__.py               # Registers the current seven nodes and frontend directory
├── lux3d_openapi/            # OpenAPI client, contracts, polling, and five task nodes
├── lux3d_material.py         # Lux3D Material Redraw node
├── lux3d_viewer.py           # Lux3D Viewer node
├── viewer_asset_routes.py    # Viewer static-asset routes
├── viewer_assets/            # Viewer runtime assets shipped with the plugin
├── frontend/                 # Viewer/input-source extension source and tests
├── js/                       # Frontend build loaded by ComfyUI
├── tests/                    # Python tests
├── requirements.txt          # Python runtime dependencies
├── README.md                 # English documentation
└── README_CN.md              # Chinese documentation

Dependencies

| Dependency | Version | Purpose | License | | --- | --- | --- | --- | | requests | >=2.25.0 | HTTP client for API calls | Apache 2.0 | | Pillow | >=9.0.0 | Image processing | BSD | | NumPy | >=1.21.0 | Scientific computing | BSD |

Configuration

Server environment variables

The currently registered nodes do not read config.txt or expose an API-key input in the workflow. Set the variable matching base_api_path in the environment of the process that starts ComfyUI:

| base_api_path | Environment variable | | --- | --- | | https://api.aholo3d.cn | LUX3D_API_KEY_CN | | https://api.aholo3d.com | LUX3D_API_KEY_INTL |

PowerShell example:

$env:LUX3D_API_KEY_CN = "your_cn_api_key"
$env:LUX3D_API_KEY_INTL = "your_intl_api_key"

Bash example:

export LUX3D_API_KEY_CN="your_cn_api_key"
export LUX3D_API_KEY_INTL="your_intl_api_key"

If you use only one region, set only its variable. The variables must be visible to the ComfyUI server process; restart ComfyUI after changing them. Lux3D Viewer does not call the Lux3D API and therefore needs no API key.

License

MIT