JinDaGe - Lux3d-cn Skill Details

本技能的功能

Lux3D 通过三个文档化的异步工作流生成 3D 资产：

图片生成 3D：提交输入图片，轮询任务，然后下载 ZIP 结果。
文本生成 3D：提交提示词和可选风格（可选择附带参考图片），轮询任务，然后下载 ZIP 结果。
模型材质重绘：提交参考图片和模型 URL，轮询任务，然后下载重绘后的模型结果。

两种工作流都需要 LUX3D_API_KEY，这是从 https://labs.aholo3d.cn/api-keys 获取的 API 密钥。

API 端点

国内端点：https://api.aholo3d.cn

环境配置

申请 API 密钥

注册地址：https://labs.aholo3d.cn/api-keys

设置环境变量

必需：

export LUX3D_API_KEY="your_api_key"

可选 - 覆盖基础 URL：

export LUX3D_BASE_URL="https://api.aholo3d.cn"

可选 - 指定区域（推荐）：

export LUX3D_REGION="cn"

Python 用法

图片生成 3D

from skill.lux3d_client import generate_3d_model

result = generate_3d_model("path/to/input.jpg", region="cn")
print(result)

文本生成 3D

from skill.lux3d_client import generate_text_to_3d

result = generate_text_to_3d(
    "生成一个高质量的 3D 木椅",
    region="cn",
)
print(result)

文本加参考图片

from skill.lux3d_client import generate_text_to_3d

result = generate_text_to_3d(
    "生成一个带有光泽釉面的高级陶瓷花瓶",
    style="glass",
    image_path="path/to/reference.png",
    region="cn",
)
print(result)

底层任务 API

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", region="cn")
text_task_id = create_text_to_3d_task(
    "生成一个风格化的玩具机器人",
    style="cartoon",
    image_path="path/to/reference.png",
    region="cn",
)
material_task_id = create_material_transfer_task(
    "path/to/reference.png",
    mesh_url="https://example.com/model.glb",
    region="cn",
)

image_model_url = query_task_status(image_task_id, region="cn")
text_model_url = query_task_status(text_task_id, region="cn")
material_model_url = query_task_status(material_task_id, region="cn")

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")

模型材质重绘

from skill.lux3d_client import generate_material_transfer

result = generate_material_transfer(
    "path/to/reference.png",
    mesh_url="https://example.com/model.glb",
    region="cn",
)
print(result)

命令行用法

区域选择

使用 --region 或 -r 选择国内端点：

python lux3d_client.py -r cn image input.jpg output.zip

或设置环境变量：

export LUX3D_REGION="cn"
python lux3d_client.py image input.jpg output.zip

图片生成 3D

# 传统格式
python lux3d_client.py -r cn input.jpg output.zip

# 显式命令
python lux3d_client.py -r cn image input.jpg output.zip

文本生成 3D

python lux3d_client.py -r cn text "生成一个高质量的 3D 木椅" output.zip

带参考图片的文本生成 3D

python lux3d_client.py -r cn text "生成一个未来感的台灯" output.zip --style cyberpunk --image ref.png

模型材质重绘

python lux3d_client.py -r cn material reference.png output.zip --mesh-url https://example.com/model.glb

文本生成 3D 风格

支持的风格（可选参数，默认为 photorealistic）：

| 风格 | 描述 | |------|------| | photorealistic | 照片级真实感（默认） | | cartoon | 卡通风格 | | anime | 动漫风格 | | hand_painted | 手绘风格 | | cyberpunk | 赛博朋克 | | fantasy | 奇幻风格 | | glass | 玻璃材质 |

Lux3D 版本

支持通过 version 参数指定 Lux3D 版本：

| 版本 | 说明 | 输出格式 | |------|------|------| | v2.0-preview | 默认版本，全新模型架构，重点拓展了对文字、纹理细节的保持能力，不含透明材质 | .zip + .glb + .usdz | | v1.0-pro | 首版大模型，具有完整的 PBR 材质属性输出，支持透明材质生成 | lux3d 格式 |

重要说明：若请求中不传 version 参数，系统将默认使用 v2.0-preview 版本。

所有生成接口（图片生成 3D、文本生成 3D、模型材质重绘）均支持 version 参数。

Python 中指定版本

# 图片生成 3D 指定版本
result = generate_3d_model("path/to/input.jpg", region="cn", version="v1.0-pro")

# 文本生成 3D 指定版本
result = generate_text_to_3d(
    "生成一个高质量的 3D 木椅",
    region="cn",
    version="v1.0-pro",
)

# 模型材质重绘指定版本
result = generate_material_transfer(
    "path/to/reference.png",
    mesh_url="https://example.com/model.glb",
    region="cn",
    version="v1.0-pro",
)

命令行指定版本

# 图片生成 3D 指定版本
python lux3d_client.py -r cn image input.jpg output.zip --version v1.0-pro

# 文本生成 3D 指定版本
python lux3d_client.py -r cn text "生成一个高质量的 3D 木椅" output.zip --version v1.0-pro

# 模型材质重绘指定版本
python lux3d_client.py -r cn material reference.png output.zip --mesh-url https://example.com/model.glb --version v1.0-pro

输出

结果 URL 通常指向一个 ZIP 文件，包含：

一个 GLB 模型文件
PBR 纹理资产

v2.0-preview 版本多格式输出说明：

.zip：打包结果文件，包含完整的模型和材质资源
.glb：带材质的 GLB 格式模型，适合 Web 渲染和大多数 3D 软件
.usdz：Apple AR 格式，可直接用于 iOS AR 场景（如 AR Quick Look）

结果 URL 有效期：2 小时

注意事项

使用 Authorization 请求头进行身份验证：Authorization: <apiKey>
图片生成 3D、文本生成 3D 和模型材质重绘使用不同的创建端点
三种工作流共享同一个任务查询端点
文本生成 3D 必须提供 prompt 参数，style 为可选参数（默认 photorealistic）
文本生成 3D 的 img 参数为可选，编码后应为完整的 data URL
模型材质重绘必须提供 img（材质参考图）和 meshUrl（模型 GLB 文件地址）参数

依赖要求

pip install Pillow requests

参考资料

Lux3D 官网：https://lux3d.aholo3d.cn/
API 密钥申请：https://labs.aholo3d.cn/api-keys
API 联系方式：lux3d@qunhemail.com