---
name: lux3d
description: "Use Lux3D to generate 3D models from images or text, or perform material transfer. Trigger when the user asks for image to 3D, text to 3D, prompt to 3D, create a 3D model from a description, create a 3D model from a description plus a reference image, or regenerate materials for an existing 3D model. For international users."
---

## What This Skill Does

Lux3D generates 3D assets through three documented asynchronous workflows:

- **Image to 3D**: submit an input image, poll the task, then download the ZIP result.
- **Text to 3D**: submit a prompt plus style, optionally with a reference image, poll the task, then download the ZIP result.
- **Material Transfer**: submit a reference image and a model URL, poll the task, then download the regenerated model result.

All workflows require `LUX3D_API_KEY`, which is the API key obtained from https://labs.aholo3d.com/api-keys.

## API Endpoint

- **International Endpoint**: `https://api.aholo3d.com/global`

## Setup

### Apply for an API Key

- Register at: https://labs.aholo3d.com/api-keys

### Set Environment Variables

**Required:**

```bash
export LUX3D_API_KEY="your_api_key"
```

**Optional - Override Base URL:**

```bash
export LUX3D_BASE_URL="https://api.aholo3d.com/global"
```

**Optional - Specify Region:**

```bash
export LUX3D_REGION="international"
```

## Python Usage

### Image to 3D

```python
from skill.lux3d_client import generate_3d_model

result = generate_3d_model("path/to/input.jpg", version="v2.0-preview")
print(result)
```

Or explicitly specify international region:

```python
result = generate_3d_model("path/to/input.jpg", region="international", version="v2.0-preview")
print(result)
```

### Text to 3D

```python
from skill.lux3d_client import generate_text_to_3d

result = generate_text_to_3d(
    "Generate a high-quality 3D wooden chair",
    style="photorealistic",
    version="v2.0-preview",
)
print(result)
```

### Text plus Reference Image

```python
from skill.lux3d_client import generate_text_to_3d

result = generate_text_to_3d(
    "Generate a premium ceramic vase with a glossy glaze",
    style="glass",
    image_path="path/to/reference.png",
    version="v2.0-preview",
)
print(result)
```

### Low-level Task APIs

```python
from skill.lux3d_client import (
    create_task,
    create_text_to_3d_task,
    create_material_transfer_task,
    query_task_status,
    download_model,
)

image_task_id = create_task("path/to/input.jpg")
text_task_id = create_text_to_3d_task(
    "Generate a stylized toy robot",
    style="cartoon",
    image_path="path/to/reference.png",
)
material_task_id = create_material_transfer_task(
    "path/to/reference.png",
    mesh_url="https://example.com/model.glb",
)

image_model_url = query_task_status(image_task_id)
text_model_url = query_task_status(text_task_id)
material_model_url = query_task_status(material_task_id)

download_model(image_model_url, "image_to_3d.zip")
download_model(text_model_url, "text_to_3d.zip")
download_model(material_model_url, "material_transfer.zip")
```

### Material Transfer

```python
from skill.lux3d_client import generate_material_transfer

result = generate_material_transfer(
    "path/to/reference.png",
    mesh_url="https://example.com/model.glb",
    version="v2.0-preview",
)
print(result)
```

## Command Line Usage

### Region Selection

Use `--region` or `-r` to select the international endpoint (default):

```bash
python lux3d_client.py --region international image input.jpg output.zip
```

Or simply omit the region flag (international is default):

```bash
python lux3d_client.py image input.jpg output.zip
```

### Image to 3D

```bash
# Historical form (default region)
python lux3d_client.py input.jpg output.zip --version v2.0-preview

# Explicit command
python lux3d_client.py image input.jpg output.zip --version v2.0-preview
```

### Text to 3D

```bash
python lux3d_client.py text "Generate a high-quality 3D wooden chair" output.zip --style photorealistic --version v2.0-preview
```

### Text to 3D with Reference Image

```bash
python lux3d_client.py text "Generate a futuristic desk lamp" output.zip --style cyberpunk --image ref.png --version v2.0-preview
```

### Material Transfer

```bash
python lux3d_client.py material reference.png output.zip --mesh-url https://example.com/model.glb --version v2.0-preview
```

## Text-to-3D Styles

Supported styles:

| Style | Description |
|-------|-------------|
| `photorealistic` | Photorealistic quality |
| `cartoon` | Cartoon style |
| `anime` | Anime style |
| `hand_painted` | Hand-painted style |
| `cyberpunk` | Cyberpunk theme |
| `fantasy` | Fantasy style |
| `glass` | Glass material |

## Lux3D Version

You can specify the Lux3D version via the `version` parameter:

| Version | Description |
|---------|-------------|
| `v1.0-pro` | Default version, stable release |
| `v2.0-preview` | Preview version |

All generation APIs (image-to-3D, text-to-3D, material transfer) support the `version` parameter.

### Specify Version in Python

```python
# Image to 3D with version
result = generate_3d_model("path/to/input.jpg", version="v2.0-preview")

# Text to 3D with version
result = generate_text_to_3d(
    "Generate a high-quality 3D wooden chair",
    style="photorealistic",
    version="v2.0-preview",
)

# Material transfer with version
result = generate_material_transfer(
    "path/to/reference.png",
    mesh_url="https://example.com/model.glb",
    version="v2.0-preview",
)
```

### Specify Version in Command Line

```bash
# Image to 3D with version
python lux3d_client.py image input.jpg output.zip --version v2.0-preview

# Text to 3D with version
python lux3d_client.py text "Generate a high-quality 3D wooden chair" output.zip --style photorealistic --version v2.0-preview

# Material transfer with version
python lux3d_client.py material reference.png output.zip --mesh-url https://example.com/model.glb --version v2.0-preview
```

## Output

The result URL typically points to a ZIP file containing:

- A GLB model file
- PBR texture assets

Result URL validity: **2 hours**

## Notes

- Authentication uses `Authorization` header: `Authorization: <apiKey>`
- Image-to-3D, text-to-3D, and material transfer use different create endpoints
- All three workflows share the same task query endpoint
- `prompt` and `style` are required for text-to-3D
- `img` is optional for text-to-3D and should be a full data URL after encoding
- Material transfer requires `img` (reference image) and `meshUrl` (model GLB file URL) parameters

## Requirements

```bash
pip install Pillow requests
```

## References

- Lux3D Website: https://lux3d.aholo3d.com/
- API Key Application: https://labs.aholo3d.com/api-keys
- API contact: lux3d@qunhemail.com